Skip to main content
Version: 13.x (Current)

API portal documentation

In this tutorial, we will learn how to configure and use the API Portal and the Swagger Aggregator in order to provide the developers with a user-friendly interface that enables them to easily visualize and test endpoints of different microservices in a single place. It is built on top of the OpenAPI 2.0/OpenAPI 3.0/OpenAPI 3.1 Specification.

What we will build​

We will add the API Portal and Swagger Aggregator Marketplace plugins in a project using the dedicated Application. As a result, we will use the Portal to view and test project endpoints.

In particular, we will:

  • Set up the API Documentation Aggregator application;
  • Open the interface and test the endpoints;

Prerequisites​

info

If you have already done the previous tutorial, you can skip this section and go on using the same project.

Before starting, we will assume that, you already have a clean project in Mia-Platform Console. In order to know how to create a project on Mia-Platform Console, read this guide.

The project must:

  1. Be integrated with a deploy pipeline;
  2. Have an ingress route with api-gateway as service;
  3. Have an API Gateway or a Envoy API Gateway in your project;
  4. Have a service in your project that at least exposes:
    • an endpoint that is also reachable outside the project thanks to a proper the endpoints section configuration;
    • an endpoint, internal respect to the project, that replies with the OpenAPI documentation of the service in json format.
tip

If your are using a Mia-Platform Console in PaaS and the project has been created using the "Mia-Platform Basic Project Template", the project already satisfies conditions 1 and 2.

Moreover, you need at least:

  • developer role on the project you want to use to reproduce the steps;
  • maintainer role on the environment of the project you want to deploy on.

API Documentation Aggregator Application​

In order to start the tutorial, you must be in the design section of the project in the Microservices section from the left side menu.

Since a project is meant to have several microservices, we want to have the ability to access their documentation from a single place. To do so we need to include in our project an API Portal and a Swagger Aggregator service. We can install each plug-in manually from Mia-Platform Markeplace, but in this example we use the API Documentation Aggregator application.

This application include the following components:

  • API Portal, that will present a graphical interface to show the OpenAPI documentation of our endpoints;
  • Swagger Aggregator, that will be contacted by the API Portal to have the entire OpenAPI documentation to be shown. In order to create it, the Swagger Aggregator will retreive the OpenAPI documentation of each service and merge it into a single one.
  • you can choose to create a new API Gateway service or choose an already installed service.

and the following endpoints:

note

The /api/openapi endpoint reroute depends on which Open API Specification you want to see:

caution

In the Mia-Platform Marketplace are available two different applications to install the API Portal and Swagger Aggregator. The difference between them is the API Gateway used:

  • the API Documentation Aggregator uses the Envoy API Gateway
  • the API Documentation Aggregator NGINX uses the NGINX API Gateway

Pay attention and choose the one best suites your needs.

Install the application​

To install our API Documentation Aggregator follow the following steps:

  1. Click the Applications menu item in the Workloads section of the console left menu;
  2. Click the button Create new Application;
  3. Search the application API Documentation Aggregator in the marketplace's right panel search bar;
  4. Choose between the NGINX or the Envoy version;
  5. Follow the wizard and choose the name for service you want to create or simply choose one of the already installed service for the specific category.

create-application

Set which documentations must be aggregated​

Before testing the API Portal, we need to configure the services and endpoints in order make the Swagger Aggregator include their documentations in merged one.

Configure the service​

First of all we must make the swagger aggregator aware of the endpoints to contact in order to retrieve the documentations of the various services. Therefore, if we want a service documentation to be included in the one shown by the API Portal, we need to follow the following steps:

  1. Click on the Microservices section;
  2. Select the service to configure, in this case hello-world-service;
  3. Under the details section fill the API documentation path with the service endpoint that exposes the OpenAPI documentation, in this case /documentation/json;
  4. Save the changes by committing.

Configure service

tip

Note that api-gateway, api-portal and swagger-aggregator services should have API documentation path field blank, since we don't want to fetch any documentation from them.

Configure the endpoint​

To configure the endpoints:

  1. Click on the Endpoints section;
  2. Select the endpoint to configure, in this case /greetings;
  3. Under the Endpoint settings section in the Documentation tab check the Show in API Portal;
  4. Save the changes by committing.

Configure endpoint

caution

Be sure that those flags are unchecked for /documentations/api-portal and /documentations/api-portal/api endpoints!

Repeat these operations for each service and endpoint you want to show in the API Portal.

Once you have configured everything, you can deploy the project! 🚀

tip

If you do not know how to do it, take a quick look at Mia-Platform handbook.

Open the interface and test the endpoint​

The last step is to open the API portal interface. Firstly, go to the environments section of the Project Overview area. Now open the Environment's menu item and select "Go to Documentation" of the wanted environment, as shown in the image below:

Open docs

After clicking the link, this interface will be displayed. Here you will find and search for each endpoint exposed by API Portal, you can also try the endpoint by filling in the parameters and click on the Try it button:

API Portal

Congrats, we have now a portal for exploring and contacting all your endpoints documentation in a single place! 🎉