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).
Integrating OpenAPI specifications with LeanIX VSM will help you with:
- 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.
- 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?
- 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:
- Activate the integration via Admin > Integrations
- Create a Technical User Token from within your workspace with at least member rights
- Get the bearer token from the API Token:
Hint: you'll find theHOSTfrom 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
- 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.
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.softwareArtifactId)}"
},
"from": {
"external": {
"id": {
"expr": "${content.id}"
},
"type": {
"expr": "openapiId"
}
}
},
"to": {
"external": {
"id": {
"expr": "${content.data.metadata.softwareArtifactId}"
},
"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
Updated 7 months ago