Swagger Aggregator Configuration

This service can be added to your project by visiting Mia-Platform Marketplace and creating a new microservice from the Swagger Aggregator plugin.

It is also possible to expose your Swagger Aggregator microservice with multiple endpoints, each of them with a specific purpose. For example, you can create three endpoints with the following paths:

• /documentations/api-portal/api: this endpoint is necessary to retrieve the aggregated Open API specification document shown in the Documentation Portal through the graphical interface generated by the API Portal plugin.
• /documentations/swagger: this endpoint exposes the Swagger UI of your project. For this endpoint you should set its Rewrite Base Path to /swagger. Remember also to unset the Support only JSON format on request and Support only JSON format on response flags.
• /documentations/openapi: by calling this endpoint you will retrieve the OpenAPI specification document of your project. For this endpoint you should set its Rewrite Base Path to /openapi.

Environment variables

• CONFIG_FILE_PATH (required): defines the path of the configuration file
• TRUSTED_PROXIES: defines a list of trusted proxies ips
• MERGE_STRATEGY: defines the strategy to merge: THROWS or FIRST (default: THROWS)
• TIMEOUT_CHECKUP_PROBE_DEPENDENCIES_IN_SECOND: defines the timeout to check the probe dependencies (default 10s)
• CONCURRENT_REQUEST_LIMIT: lets you define the number of allowed concurrent requests that should be done by the service to fetch the documentations
• PREVENT_REQUEST_BODY_CONFLICTS: disables the requestBodies aggregation when converting swaggers to openApi V3; the default value is a boolean set to false

Configuration file

tip

Configure Swagger Aggregator directly from Console

This Microservice is configured via a configuration file similar to this:

module.exports = {
  title: "Documentation",
  descriptionMarkdownFilePath: "tests/DESCRIPTION.md",
  version: "1.0.0",
  services: [
    {
      type: "url",
      url: "http://localhost:3000/documentation/json",
      prefix: "/",
      includePaths: [
        {
          path: "/pathToInclude-1",
        },
        {
          path: "/pathToInclude-2",
        },
      ],
      excludePaths: [
        {
          path: "/pathToExclude-1",
        },
      ],
    },
    {
      type: "url",
      url: "http://petstore.swagger.io/v2/swagger.json",
      prefix: "/foo",
    },
    {
      type: "file",
      path: "tests/localSwaggers/localSwagger.yaml",
      prefix: "/v1",
      includePaths: [
        {
          path: "/pathToInclude-1",
        },
      ],
    },
  ],
  apiPortalConfig: {
    oauthConfig: {
      clientId: 'clientId',
      usePkceWithAuthorizationCodeGrant: true,
    }
  },
  baseSwagger: {
    swagger: "2.0",
    consumes: ["application/json"],
    produces: ["application/json"],
    securityDefinitions: {
      APISecretHeader: {
        type: "apiKey",
        in: "header",
        name: "secret",
      },
      oidc: {
        authorizationUrl: '{{authorizationUrl}}',
        flow: 'accessCode',
        scopes: {
          openid: 'openId scope',
        },
        tokenUrl: '{{tokenUrl}}',
        type: 'oauth2',
      },
    },
    security: [
      {
        APISecretHeader: [],
      },
      {
        oidc: ['openapi']
      }
    ],
  },
};

General information

First, the swagger-aggregator configuration needs generic information like title, version, and description, that will generically describe the API set provided by all microservices.

note

There are two ways to provide a description:

• using the field description: requires a simple string;
• using the field descriptionMarkdownFilePath: requires the path of a MarkDown file with the description of the swagger (if specified, the content will be shown in the Swagger UI instead of the description).

Base Swagger

The baseSwagger object contains the first-level configurations of the final merged swagger as well as all the fields defined by either OpenApi 2.0 or OpenApi 3.0 specifications.

Prefix

A prefix property can be specified in the root of the configuration object. Its value will be prepended to the paths of all the routes in the final merged swagger.

Services

The services array contains the URLs and files list from which retrieve the swaggers of every microservice; in details, there are two ways to retrieve a microservice swagger:

• URL: by specifying url as type property the swagger-aggregator will download the microservice swagger from the provided url property. For this service type, the required properties will be type, url, and prefix.
• File: by specifying file as type property the swagger-aggregator will take the microservice swagger configurations from the provided path property. For this service type, the required properties will be type, path, and prefix. The file must be mounted in the swagger-aggregator service using a custom config-map.

In both of them, the user must specify a prefix that will be placed before the url or the file path. Any string that begins with / is accepted.

info

Passing the string / as prefix means that no prefix will be added to your service URLs or paths.

In both service types, the user can specify includePaths and excludePaths optional properties to filter the routes to be accessible in the swagger documentation. The filter will include first all the routes according to the objects present in the includePaths property, then the result will be filtered by the objects present in the excludedPaths property.

Both properties should be an array of objects and each object requires a path property. In each object, it is also possible to define a verb property that specifies which verb of that specific path should be included/excluded.

{
  "type": "url",
  "url": "http://petstore.swagger.io/v2/swagger.json",
  "prefix": "/foo",
  "includePaths": [
    {
      "path": "/pathToInclude-1"
    },
    {
      "path": "/pathToInclude-2",
      "verb": "get"
    }
  ],
  "excludePaths": [
    {
      "path": "/pathToInclude-1/pathToExclude-1"
    }
  ]
}

Here there is a list of the routes that will or will not be shown in the aggregated swagger documentation based on the example above:

• /pathToInclude-1/clients with any route verb: this route will be shown since the first part of the route path is present in the includePaths array.
• /pathToInclude-3 with any route verb: this route will not be shown since the first part of the route path is not present in the includePaths array.
• /pathToInclude-1/pathToExclude-1/managers with any route verb: this route will not be shown since the first part of the route path is present in the excludePaths array.
• /pathToInclude-2 with get verb: this route will be shown since the route path precisely matches the one present in the includePaths array with the same verb.
• /pathToInclude-2 with post verb: this route will not be shown because, even if the route path precisely matches the one present in the includePaths array, the specified verb is different.
• /pathToInclude-2/customers with get verb: this route will not be shown because the route path does not precisely match the one present in the includePaths array, even if the specified verb is the same.

caution

It is important to notice that the behavior of these two properties changes depending on the presence of the verb property. If verb property is not defined all sub-routes that match the path property will be included/excluded.

Otherwise, if verb property is defined, only the routes that exactly match the path and verb property will included/excluded.

It is also possible to transform paths and apply custom tags to them with transformPaths property.

{
  "type": "url",
  "url": "http://petstore.swagger.io/v2/swagger.json",
  "prefix": "/foo",
  "transformPaths": {
    "/myPath": [
      {
        "path": "/my-path",
        "tags": ["Custom Tag"],
        "verbsToTransform": ["get", "post"]
      },
      {
        "path": "/my-path2",
        "tags": ["Some other custom tag"]
      }
    ]
  }
}

Here is a list of the routes that will or will not be transformed in the aggregated swagger documentation based on the example above:

• /myPath with get verb: this route will be transformed into two different routes /my-path and /my-path2 with the specified tags and get verb.
• /myPath with delete verb: this route will be transformed into another route /my-path2 with Some other custom tag as tag and delete verb.
• /yourPath with any verb: this route will not be transformed since it does not match any transformPath.
• /myPath/customers with get verb: this route will be transformed into another route /my-path2/customers with Some other custom tag as tag and get verb. It will not be transformed into /my-path/customers because it does not exactly match path property.

caution

It is important to notice that the behavior of transformPaths property changes depending on the presence of verbsToTransform property. If verbsToTransform property is not defined all sub-routes that match the path property will be transformed.

Otherwise, if verbsToTransform property is defined, only the routes that exactly match the path and verb properties will be transformed.

caution

Please be sure to validate the configuration with the following JSON schema before running the service, otherwise the microservice will not correctly start.

info

For additional information about more advanced properties that can be defined in the swagger-aggregator configuration (e.g., subSwaggers property) visit this page.

Security

In order to change the default security method edit the items baseSwagger.securityDefinitions and baseSwagger.security in the configuration file.

Here is an example of how to enable bearer token authorization according to the official OpenAPI documentation

"baseSwagger": {
  "securityDefinitions": {
    "BearerToken": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "JWT"
    }
  },
  "security": [
    {
      "BearerToken": []
    }
  ]
}

Customize API Portal

With the key apiPortalConfig, it is possible to:

• customize the API Portal logo and/or favicon
• change the API Portal endpoints prefix.
• set oauthConfig object. It contains the configuration useful for the OAuth 2.0 authentication. It's the same of the swagger-ui OAuth 2.0 configuration.

You can read at the following links how to:

• change the logo
• change the API Portal prefix
• authenticate endpoints with OAuth 2.0

{
  ...
  "apiPortalConfig": {
    "apiPrefix": "/custom-prefix",
    "logoUrl": "/your-logo-url",
    "faviconUrl": "/your-favicon-url",
    "oauthConfig": { ... }, 
  },
}

FAQs

You can find some FAQs about Swagger Aggregator and API Portal at this link.