Skip to main content

Swagger

In this example you are going to create a swaggerPath blueprint that ingests all API paths in your swagger.json file using a combination of Port's API and webhook functionality.

To ingest the API paths to Port, a script that sends information about the paths according to the webhook configuration is used.

Prerequisites​

Create the following blueprint definition and webhook configuration:

Swagger path blueprint
{
  "identifier": "swaggerPath",
  "description": "This blueprint represents a Swagger path in our software catalog",
  "title": "Swagger API Paths",
  "icon": "Swagger",
  "schema": {
    "properties": {
      "method": {
        "type": "string",
        "title": "Method",
        "default": "get",
        "enum": ["get", "post", "delete", "put", "patch"],
        "enumColors": {
          "get": "yellow",
          "post": "green",
          "delete": "red",
          "put": "purple",
          "patch": "purple"
        }
      },
      "host": {
        "type": "string",
        "title": "API Base URL",
        "format": "url"
      },
      "path": {
        "title": "Path",
        "type": "string"
      },
      "parameters": {
        "items": {
          "type": "object"
        },
        "title": "Parameters",
        "type": "array"
      },
      "responses": {
        "title": "Responses",
        "type": "object"
      },
      "description": {
        "title": "Description",
        "type": "string"
      },
      "version": {
        "title": "Version",
        "type": "string"
      },
      "summary": {
        "title": "Summary",
        "type": "string"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "relations": {}
}
Swagger path webhook configuration
{
  "identifier": "swaggerPathMapper",
  "title": "Swagger Path Mapper",
  "description": "A webhook configuration to map Swagger JSON file",
  "icon": "Swagger",
  "mappings": [
    {
      "blueprint": "swaggerPath",
      "itemsToParse": ".body.paths",
      "entity": {
        "identifier": ".item.id | sub(\"[^A-Za-z0-9@_.:/=-]\"; \"-\"; \"g\")",
        "title": ".item.method + .item.path",
        "properties": {
          "method": ".item.method",
          "host": ".item.host",
          "path": ".item.path",
          "parameters": ".item.parameters",
          "responses": ".item.responses",
          "description": ".item.description",
          "version": ".item.version",
          "summary": ".item.summary"
        }
      }
    }
  ],
  "enabled": true,
  "security": {}
}

Working with Port's API and Bash script​

Here is an example snippet showing how to integrate Port's API and Webhook with your existing pipelines using Python and Bash:

Create the following Python script in your repository to create or update Port entities as part of your pipeline:

Python script example 
## Import the needed libraries

import requests
import json
import os

# Get environment variables using the config object or os.environ["KEY"]
WEBHOOK_URL = os.environ['WEBHOOK_URL'] ## the value of the URL you receive after creating the Port webhook
PATH_TO_SWAGGER_JSON_FILE = os.environ["PATH_TO_SWAGGER_JSON_FILE"]


def add_entity_to_port(entity_object):
    """A function to create the passed entity in Port using the webhook URL

    Params
    --------------
    entity_object: dict
        The entity to add in your Port catalog

    Returns
    --------------
    response: dict
        The response object after calling the webhook
    """
    headers = {"Accept": "application/json"}
    response = requests.post(WEBHOOK_URL, json=entity_object, headers=headers)
    return response.json()


def read_swagger_file(swagger_json_path):
    """This function takes a swagger.json file path, converts the "paths" property into a
    JSON array and then sends this data to Port

    Params
    --------------
    swagger_json_path: str
        The path to the swagger.json file relative to the project's root folder

    Returns
    --------------
    response: dict
        The response object after calling the webhook
    """
    with open(swagger_json_path) as file:
        data = json.load(file)

    project_info = data.get("info")
    project_title = project_info.get("title")
    project_version = project_info.get("version")
    hosted_url = data.get("host")
    base_path = data.get("basePath")

    paths = data.get('paths', {})
    path_list = []
    index = 1
    for path, methods in paths.items():
        for method, method_info in methods.items():
            path_id = f"{project_title}-{index}"
            path_info = {
                "id": path_id,
                "path": path,
                "method": method,
                "summary": method_info.get('summary'),
                "description": method_info.get('description'),
                "parameters": method_info.get("parameters"),
                "responses": method_info.get("responses"),
                "project": project_title,
                "version": project_version,
                "host": "https://" + hosted_url + base_path
            }
            path_list.append(path_info)
            index+=1

    entity_object = {
        "paths": path_list
    }
    webhook_response = add_entity_to_port(entity_object)
    return webhook_response

response = read_swagger_file(PATH_TO_SWAGGER_JSON_FILE)
print(response)