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)