Skip to main content


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.


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": " | sub(\"[^A-Za-z0-9@_.:/=-]\"; \"-\"; \"g\")",
"title": ".item.method + .item.path",
"properties": {
"method": ".item.method",
"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

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

entity_object: dict
The entity to add in your Port catalog

response: dict
The response object after calling the webhook
headers = {"Accept": "application/json"}
response =, 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

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

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

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)