OpenAPI / Swagger

Integrate OpenAPI specifications version 2 and 3

Introduction

With the widespread adoption of OpenAPI (or SwaggerSpec for versions up to 2) to universally describe & build APIs LeanIX now allows incorporating that information to help you understand and govern your APIs more efficiently.

We are able to seamlessly embed into your existing API development workflow: whether your organization follows a Code-First or a Design-First approach. Besides integrating API Factsheets itself, the integration will also eventually be able to create respective Software Artifact & Team linkages (if provided).

12621262

Integrating OpenAPI specifications with LeanIX VSM will help you with:

  1. API Ownership: understanding more quickly which development team is responsible for a given API to supercharge your dev team productivity and reuse of existing APIs.
  2. Impact Analysis: creating transparency around which (micro-)services are using/providing an API to drive smart architecture decisions. Wouldnt it be nice to know, where to look if things go down south?
  3. Business Context: providing an intuitive map showing APIs in their domain (e.g. Customer Service, Payment, etc.) to help you streamline API (re-)usage across different (business) domains.

Setup

Whether you are following a Code-First or Design-First approach, we can integrate the resulting OpenAPI specification into LeanIX VSM.

The most convenient option will probably be to add a step/ job in your build pipelines to include the below curls (see for example GitHub Actions) to automatically provide the OpenAPI specification on every CI/CD run.

Surely, you can also provide the OpenAPI specifications also by other means to the API (e.g. scripting, etc.)

📘

Best Practice

If you're not doing it already, it makes a lot of sense to store the OpenAPI specification for any given service in its repository to leverage versioning via your Git Provider as you evolve the service / API. This will also help you provide the OpenAPI specification easier from your build pipeline to LeanIX VSM.

In a Design-First approach, you'll probably already leverage a Git Provider. Hence, the below steps will be identical.

Configuration

Below steps detail how you can use the endpoint to provide the OpenAPI specification file, as well as additional metadata to incorporate into your VSM workspace:

  1. Activate the integration via Admin > Integrations
396396
  1. Create a Technical User Token from within your workspace with at least member rights
  2. Get the bearer token from the API Token:
    Hint: you'll find the HOST from your workspace URL e.g. https://<host>.leanix.net
curl --request POST \
  --url https://<HOST>/services/mtm/v1/oauth2/token \
  -u apitoken:<API TOKEN> \
  --data grant_type=client_credentials
  1. Send the OpenAPI specification as JSON data, as well as other contextual information about the API (e.g. relevant Team, Software Artifact providing the API etc.) to the OpenAPI endpoint
curl -X POST \
  -H 'Cache-Control: no-cache' \
  -H 'Authorization: Bearer <auth>'\
  -H 'Content-Type: multipart/form-data' \
  -F [email protected]<abosolute path to openapi spec file> \
  -F 'data={
  "softwareArtifactId": "swa-001",
  "url": "https://<host>/services/someService/v2/openapi.json",
  "teamExternalId": "team-001"
}' \
  https://<host>/services/cicd-connector/v2/openapispec

Find more about how to use the 'data' field in the tutorials section in order to supplement the OpenAPI with other external data (e.g. providing Software Artifact, SwaggerUI URL etc.)

📘

Tutorial - Integrating into Build Pipeline

In this tutorial, we guide you on how to embed the endpoint into your build pipeline for a seamless developer experience.

Imported Data

Below you find how objects fetched from the OpenAPI specification are translated into LeanIX Factsheets and attributes on them. Please consider this work-in-progress as this integration is developed.

OpenAPI Specification

LeanIX Value Stream Management

OpenAPI Specification Document

API Fact Sheet
Core Metadata:

  • API Version
  • OpenAPI Specification Version
  • License

Contacts specified in the info section

Subscribers on API Fact Sheet

Extending the Integration

Integration also supports Integration API execution groups via Integration Hub to enable users to add custom processors. To process the data correctly, you need to add a custom processor set.

Unique execution group name for the integration is vsmOpenAPIInbound

The integration API will pick up your processors and merge them with the base processors at execution time. Make sure to set the Integration API run number accordingly.

Below there is a collection of tutorials on how you can use the OpenAPI endpoint to cater to your needs

For more information on the execution, groups visit the Integration API documentation

Tutorials

Contextualising your APIs from OpenAPI specifications with additional metadata

You might have information that is external to the OpenAPI specification but would make sense for you to contextualize your APIs in VSM with - think owning team, the link to your SwaggerUI, the providing Software Artifact, etc.

In this use case, we add the following properties to the endpoint and later use the data in the LDIF as mentioned in the purpose column.

Data

Purpose

microserviceId

Create a relation to the providing Software Artifact FactSheet

URL to SwaggerUI

Create a document in the resources tab of the API FactSheet, that links to specification

1. Pass data to the endpoint

via cUrl
curl -X POST \
  -H 'Cache-Control: no-cache' \
  -H 'Authorization: Bearer <auth>'\
  -H 'Content-Type: multipart/form-data' \
  -F [email protected]<abosolute path to openapi spec file> \
  -F 'data={
  "microserviceId": "SVC-00001",
  "url": "https://demo-eu-1.leanix.net/services/pathfinder/v1/api-docs/swagger.json"
}' \
  https://demo-eu-1.leanix.net/services/cicd-connector/v2/openapispec
(or) via GitHubActions

📘

Usage

This use case is an extension to the tutorial discussed here

Update the main.yml in .github>workflows>main.yml of https://github.com/leanix-public/dropwizard-hello-world/tree/main repository
Change the LeanIX OpenAPI Integration (the last step in the job) to include the data parameter

      - name: LeanIX OpenAPI Integration
        id: leanix-openapi
        if: ${{steps.gen-bearerToken.outputs.bearerToken}}
        uses: fjogeleit/[email protected]
        with:
          url: https://${{ env.LEANIX_WORKSPACE_TEST_FQDN }}/services/cicd-connector/v2/openapispec
          method: 'POST'
          contentType: 'multipart/form-data'
          bearerToken: ${{steps.gen-bearerToken.outputs.bearerToken}}
+          data: '{"data": "{  \"softwareArtifactId\": \"swa-001\",  \"url\": \"https://<host>/services/someService/v2/openapi.json\"}"}'
          files: '{ "specRequest": "${{ github.workspace }}/generated/OpenAPI-Specification.json" }'
          timeout: 60000

2.Examine the LDIF from OpenAPI integration

LDIF structure can be fetched from one of the previous sync logs.

"content": [
        {
            "type": "api",
            "id": "Hello World Service/1.0.0",
            "data": {
                "name": "Hello World Service",
                "tags": [],
                "paths": [
                    {
                        "path": "/",
                        "tags": [],
                        "httpMethod": "get",
                        "operationId": "getHello"
                    }
                ],
                "licence": "Apache 2.0",
                "version": "1.0.0",
+                "metadata": {
+                    "url": "https://demo-eu-1.leanix.net/services/pathfinder/v1/api-docs/swagger.json",
+                    "teamId": "TEAM-00002",
+                   "microserviceId": "SVC-00001"
                },
                "serverUrl": "https://services.exmple.it/base/path",
                "contactName": "LeanIX Support",
                "description": "A simple service which hosts an API",
                "contactEmail": "[email protected]",
                "specificationVersion": "3.0.1",
                "canonicalSpecificationVersion": "OAS3"
            }
        }
    ]

3. Create custom Integration API processors for OpenAPI integration

Make sure you set the processing direction to inbound and the processing mode to full.

10821082

Integration API processor configuration

{
    "processors": [
        {
            "processorType": "inboundRelation",
            "processorName": "Rel from API to SoftwareArtifact",
            "processorDescription": "Creates LeanIX Relations between the created or updated API and providing Microservice",
            "type": "relAPIToProviderMicroservice",
            "filter": {
                "advanced": "${content.type == 'api' && !(empty content.id) && !(empty content.data.metadata.microserviceId)}"
            },
            "from": {
                "external": {
                    "id": {
                        "expr": "${content.id}"
                    },
                    "type": {
                        "expr": "openapiId"
                    }
                }
            },
            "to": {
                "external": {
                    "id": {
                        "expr": "${content.data.metadata.microserviceId}"
                    },
                    "type": {
                        "expr": "microserviceId"
                    }
                }
            },
            "run": 3
        },
        {
            "processorType": "inboundDocument",
            "processorName": "Add Documents",
            "processorDescription": "Contains the link that will point to the documentation for the respective FactSheet",
            "identifier": {
                "external": {
                    "id": {
                        "expr": "${content.id}"
                    },
                    "type": {
                        "expr": "openapiId"
                    }
                }
            },
            "run": 3,
            "updates": [
                {
                    "key": {
                        "expr": "url"
                    },
                    "values": [
                        {
                            "expr": "${content.data.metadata.url}"
                        }
                    ]
                },
                {
                    "key": {
                        "expr": "name"
                    },
                    "values": [
                        {
                            "expr": "OpenAPI Spec Documentation"
                        }
                    ]
                },
                {
                    "key": {
                        "expr": "documentType"
                    },
                    "values": [
                        {
                            "expr": "documentation"
                        }
                    ]
                }
            ]
        }
    ],
    "variables": {},
    "executionGroups": [
        "vsmOpenAPIInbound"
    ]
}

4.Trigger the OpenAPI Integration

Once the custom processors are ready, invoke the endpoint with the required metadata and a new resource would be created on the API FactSheet & relation to the Providing Microservice FactSheet

20702070 24382438

Did this page help you?