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

API Portal Configuration

The API Portal microservice can be added to your project by visiting Mia-Platform Marketplace. It works best with the Swagger Aggregator but it's possible to use it with a custom microservice if the correct data are returned.

note

You can select the API Documentation application on the Marketplace to have a ready-to-use API Portal that works with the Swagger Aggregator microservice.

Routes​

The API Portal requires to expose two routes: /api/openapi/ and /api/openapi/raw/.

The main endpoints are:

  • /api/openapi/json: it expects a compliant Open API specification document. All versions are supported;

  • /api/openapi/subswaggers/: it expects an array of objects like [{"name": "<subswagger-name>", "categoryUrl": "<subswagger-url>"}]. The categoryUrl is joined, using path.join, with /api/openapi/json. To understand what is a subswagger, please see this page.

The endpoints regarding the downloads are:

  • /api/openapi/raw/swagger/json and /api/openapi/raw/swagger/yaml: it expects a Open API v2 (swagger) object in json and yaml format respectively

  • /api/openapi/raw/openapi/v3/json and /api/openapi/raw/openapi/v3/yaml: it expects a Open API v3 object in json and yaml format respectively

  • /api/openapi/raw/openapi/v3-1/json and /api/openapi/raw/openapi/v3-1/yaml: it expects a Open API v3.1 object in json and yaml format respectively

When a category is selected, it calls all the paths above, except for the subswaggers endpoint, joined with the corresponding categoryUrl. For example, if the selected category has categoryUrl = ../category1.json, the routes called will be:

  • /api/openapi/category1.json
  • /api/openapi/raw/swagger/category1.json and /api/openapi/raw/swagger/category1.json/yaml
  • /api/openapi/raw/openapi/v3/category1.json and /api/openapi/raw/openapi/v3/category1.json/yaml
  • /api/openapi/raw/openapi/v3-1/category1.json and /api/openapi/raw/openapi/v3-1/category1.json/yaml

Environment variables​

The API Portal accepts the following environment variables:

  • HTTP_PORT (default: 8080): defines the http port to use

How to migrate to v2​

To migrate from the v1.16.14, you have to:

  1. Make sure to update the Swagger Aggregator microservice to the latest version (3.6.0 or above).
  2. Remove the following endpoints:
    • /documentations/api-portal/api/openapi/v3
    • /documentations/api-portal/api
    • /documentations/openapi
    • /documentations/swagger
  3. Add the following endpoints:
    • Endpoint 1:
      • Base path: /api/openapi
      • Type: Microservice
      • Microservice: swagger-aggregator
      • Rewrite base path: it depends on the documentation version you want to see.
        • /openapi/v3-1 for Open API v3.1
        • /openapi/v3 for Open API v3.0
        • /openapi/v2 for Swagger v2
    • Endpoint 2:
      • Base path: /api/openapi/raw
      • Type: Microservice
      • Microservice: swagger-aggregator
      • Rewrite base path: /

Now you should have only three endpoints related to the API Portal: /documentations/api-portal (or whathever url you decided to expose it), /api/openapi and /api/openapi/raw