Document your services

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 Specification.

What we will build

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

In particular, we will:

• Set up the API Portal plugin;
• Set up the Swagger Aggregator plugin;
• Configure the services and endpoints to be displayed in the API Portal;
• 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.

Install plugins

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 this, we will include:

• an API Portal, that will present a graphical interface to show the OpenAPI documentation of our endpoints;
• a 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.

API Portal

The first plugin we are going to create is the API portal. The steps to create it are:

1. Click on the Create a Microservice button;
2. In the dropdown menu, select From Marketplace option;
3. On the right side, you will see a catalogue of plugin, templates and examples;
4. Type API portal in the search bar;
5. Select the API portal card from the list of result;
6. Click on the Create button applying the default fields.
7. Save the changes by committing. If you do not know how to do it, take a quick look at Mia-Platform handbook first.

Swagger Aggregator

In order to create this plugin:

1. Click on the Create a Microservice button;
2. In the dropdown menu, select From Marketplace option;
3. On the right side, you will see a catalogue of plugin, templates and examples;
4. Type Swagger Aggregator in the search bar;
5. Select the card from the list of result;
6. Click on the Create button applying the default fields.
7. Save the changes by committing.

Configure plugins endpoints

Now we need to create the necessary endpoints that are required to make the whole system work. This consists of going to the endpoints section and creating:

1. /documentations/api-portal having the following configuration:
   • Base path: /documentations/api-portal;
   • Type: "Microservice";
   • Microservice: "api-portal";
   • Rewrite Base Path: /;
2. /documentations/api-portal/api having the folowing configuration:
   • Base path: /documentations/api-portal/api;
   • Type: "Microservice";
   • Microservice: "swagger-aggregator";
   • Rewrite Base Path: /;

Remember to save your changes!

tip

If you don't know how to create an endpoint look at the first tutorial!

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.

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.

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 Settings. Now open the Environment's menu item and select "Go to Documentation" of the wanted environment, as shown in the image below:

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:

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