Tutorial: Include OpenAPI
Guide to use LeanIX OpenAPI integration in project build pipelines
The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows discovery of services without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.
LeanIX OpenAPI Integration leverages this OpenAPI Specification document of your service to generate insights into your organisation's RESTful APIs. API Discovery and much more. Please read more about LeanIX OpenAPI Integration here
The goal is to integrate LeanIX OpenAPI integration in a Maven project's build pipeline. Currently, LeanIX provides a RESTful API Endpoint which expects an OpenAPI Specification as a file.
OpenAPI specification file generation
If your project contains the related spec file in JSON format as part of the project structure, you can directly skip to section 'Integrate to build pipeline'
In this tutorial we are going to use a sample maven project, which can be found here(https://github.com/leanix-public/dropwizard-hello-world). The sample maven project exposes a simple RESTful APIs and uses OpenAPI 3.0 (Swagger 2.0) for API documentation.
- Clone the Sample Maven Project from here
- Since this is a Java project, make sure
mavenis available and
Java 8or above is also installed
Steps to follow
Once you have cloned the project and made sure that the required software is installed and available in your environment.
One thing to note is this sample project does not contain the OpenAPI spec file in the project structure. We need to generate this JSON file during the build phase and then send the generated file to the LeanIX OpenAPI endpoint.
mvn clean packagein the project root folder in the terminal
- After the build is successful, you will observe a message similar to the image below
- Inside the project root folder, you will find a new folder
generatedwhich contain the generated OpenAPI Specification file for the current project.
Spec file generation
In this project, we included a plugin
swagger-maven-pluginin our maven build phase, with some configurations such as file paths, contact information, etc.. There are other plugins such as
swagger-maven-pluginwhich could also be used.
Now that we have successfully generated the Specification file as part of the build command. It is time to look into automating things.
Trigger this workflow
Fork this repository to your GitHub. Configure the workflow to integrate with your LeanIX workspace. More details regarding the configuration can be found below
Integrate to build pipeline
In this project, we use GitHub actions to trigger a workflow whenever a push happens on the
master branch. The workflow can be found in the following path:
There are two LeanIX specific variables that needs to add correctly after you fork this repository into your GtiHub.
- LEANIX_WORKSPACE_FQDN: Your workspace host URL (Ex: demo-eu-1.leanix.net). This must be added as env variable in the workflow
- LEANIX_API_TOKEN: A Technical user API token with admin rights created on your LeanIX workspace. This must be stored as a GitHub secret for the forked repository
The following strategy is used in the above-mentioned
- Build the project using the
mvn compilecommand, which will generate the
swagger.json(OpenAPI Spec) file in your project directory
- Authenticate to LeanIX using the Host URL and the provided API Token of the workspace
- Now send a POST call to the LeanIX REST API endpoint with the absolute path of the generated OpenAPI spec file (/generated/OpenAPI-Specification.json).
Run build pipeline
After configuring the required secrets and environment variables in the forked repository, you could test it by triggering the workflow manually on the
develop branch or doing a simple commit and push to the
main.yml action, the workflow run can be accessed from your GitHub repository. A successful workflow run would be like the image below
The output can be checked in your corresponding LeanIX Workspace, a new API fact sheet is created as described in the LeanIX OpenAPI Integration
Find the screenshot below of the sample API fact sheet created
Adding further metadata to contextualize your discovered APIs
See the tutorial in the OpenAPI section to include metadata in the LDIF
Updated about 1 year ago