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

Swagger Aggregator Advanced Configuration

In the Advanced section of the Design Area you can configure the Swagger Aggregator.

The advanced configuration allows managing how the swagger APIs are exposed. Examples of possible configurations are:

  • Create further custom routes

  • Rewrite swagger routes to match different specifications depending on the context

  • Define sub-swaggers to expose only a subset of the whole API

  • Collect and combine swaggers from other services to expose them in a single interface as a whole.

note

This configuration affects the API documentation available in the Documentation Portal.

caution

The custom configuration can conflict with endpoints visibility and API documentation path set from the Console.

You can configure files directly from the Console: go to the Design area and click on the Advanced tab, from the list expand swagger-aggregator item. You have to edit the swagger-aggregator.json file only.

caution

In the swagger-aggregator list item is possible that you will find some .conf files. These files are now deprecated and should not be used anymore since swagger-aggregator.json file completely replaced them.

Here is the list of the deprecated .conf files:

  • urls.before.conf
  • urls.after.conf
  • description.conf
  • baseSwagger.conf
  • subswaggers.conf

Below are reported the more advanced properties that can be configured at the first level of swagger-aggregator.json file and how they can be employed to customize the Swagger Aggregator functionalities.

info

Remember that all the following properties (with the exceptions of servicesUrlsBefore and servicesUrlsAfter) can also be set through the configuration file, as described here.

servicesUrlsBefore and servicesUrlsAfter​

Use servicesUrlsBefore to add custom services from which retrieve the swaggers before the ones generated by the console. Use servicesUrlsAfter to add services after the others.

caution

These two properties do not belong to the json schema of the swagger aggregator configuration and, therefore, can not be defined in its configuration file. The only way to use servicesUrlsBefore and servicesUrlsAfter properties is through the advanced section of the Console, by adding them to the swagger-aggregator.json file.

caution

Do not edit urls.before.conf and urls.after.conf files, they are now deprecated and should not be used anymore. Add these two properties in the swagger-aggregator.json file instead.

Both properties are array where each object can have the following properties:

  • type
    • url: by specifying Url as type the swagger-aggregator will download the microservice swagger by the provided url field
    • file: by specifying file as type the swagger-aggregator will take the microservice swagger configurations by the provided path field.
  • url/path: microservice swagger url/file path
  • prefix (optional): the prefix

In both of them, the user can specify an includePaths and an excludePaths array, useful to filter the paths that are accessible from outside. The filter will include first all the paths according to the object passed by includePaths then the result will be filtered by the excludedPaths.

servicesUrlsBefore Example​

"servicesUrlsBefore":[
  {
    "type": "url",
    "url": "http://your-microservice/documentation/json",
    "prefix": "/"
  },
  {
    "type": "url",
    "url": "http://<your-microservice>/<custom-docs-path>",
    "prefix": "/one/ring/to/route/them/all"
  }
]

By adding the above servicesUrlsBefore property to the swagger-aggregator.json file you will add two services at the beginning of the services array property of the swagger configuration file. Swagger aggregator will request the swagger documentation of these two services (starting from your-microservice/documentation/json) before all other services that may be present.

subswaggers​

Use subswaggers property to define, as described briefly above, a set of sub-swaggers that represents a limited view on all the APIs that services expose within a project.

caution

Do not edit subswaggers.conf file, it is now deprecated and should not be used anymore. Add this property in the swagger-aggregator.json file instead.

There are many reasons to enable this feature, one of them could be to use them to cluster different endpoints under specific tags or to group routes so that they can be encapsulated into other projects.

subswagger Example​

{
  "/<reference-name>.json": {
    "name": "<subswagger-name>",
    "tagName": "<routes-group-name>",
    "expression": "<simple-js-filtering-expression>"
  }
}

Each element must be defined by <reference-name>.json key, which can be used as a handle in the servicesUrlsBefore to select which group should be exposed in other projects swaggers. It can include the following properties:

  • name: represents the name associated with the group in the swagger interface.
  • tagName: represents the name under which all the routes that match the expression are grouped.
  • expression: is evaluated as a simple JavaScript code that filters out from the sub-swagger group all the routes whose expression returns false.

To exploit the expression function depending on different contexts, three JS variables are provided to support the filtering process:

  • method: it represents which HTTP method can be used to call a specific route

  • path: it represents the path called for a specific route

  • tags: it is the list of tags that decorates a specific route

Here is provided an example of what a sub-swagger.conf configuration file might look likes:

subswaggers full-example​

"subswaggers": {
  "/project-name-cool-tag.json": {
    "name": "My Cool Project - Tags filter",
    "tagName": "My Cool Project 1",
    "expression": "'cool-project' in tags"
  },
  "/project-name-welcome-route.json": {
    "name": "My Cool Project - Path filter",
    "tagName": "My Cool Project 2",
    "expression": "'/cool/project/answers/welcome' === path"
  },
  "/project-name-no-get-routes.json": {
    "name": "My Cool Project 3 - Method filter",
    "tagName": "My Cool Project 3",
    "expression": "'GET' !== method"
  }
}

baseSwagger​

Use baseSwagger object to define custom paths following OpenAPI specification.

caution

Do not edit baseSwagger.conf file, it is now deprecated and should not be used anymore. Add this property in the swagger-aggregator.json file instead.

baseSwagger Example​

"baseSwagger": {
  "swagger": "2.0",
    "consumes": [
      "application/json",
    ],
    "produces": [
      "application/json",
    ],
    "securityDefinitions": {
      "APISecretHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "secret",
      },
    },
    "security": [
      {
        "APISecretHeader": [],
      },
    ],
}

prefix​

Use first level prefix property to add to all routes a prefix. This feature may be useful when using multiple API Gateways or when having a custom reverse proxy before your project.

prefix Example​

{
  "title": "Documentation",
  "descriptionMarkdownFilePath": "tests/DESCRIPTION.md",
  "version": "1.0.0",
  "prefix": "/your-prefix",
  "services": [
    {
      "type": "url",
      "url": "http://your-microservice/documentation/json",
      "prefix": "/"
    },
    {
      "type": "url",
      "url": "http://your-second-microservice/documentation/json",
      "prefix": "/second-prefix"
    }
  ],
  "baseSwagger": {
    "swagger": "2.0"
  }
}

In this example, all the routes documented by your-microservice swagger will receive /your-prefix as prefix, while all the other routes documented by your-second-microservice swagger will receive /your-prefix/second-prefix as prefix.