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

Every time /api/openapi/json is called, the API Portal also calls GET /api/openapi/raw/ui-config to retrieve an optional UI configuration object (the call is allowed to fail). At the moment, the object should have only one optional property oauthConfig which should be and object containing a swagger-ui OAuth 2.0 configuration.

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