Tutorial: Include OpenAPI

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

Goal

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'

Requirements

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 maven is available and Java 8 or 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.

  • Run mvn clean package in 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 generated which contain the generated OpenAPI Specification file for the current project.

📘

Spec file generation

In this project, we included a plugin swagger-maven-plugin in our maven build phase, with some configurations such as file paths, contact information, etc.. There are other plugins such as swagger-maven-plugin which 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:
.github>workflows>main.yml

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 main.yml file,

• Build the project using the mvn compile command, 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 master or develop branch or doing a simple commit and push to the develop branch

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