Version: 7.x (Current)

Swagger Aggregator Advanced Configuration

In the advanced tab of the Console Design section you can configure the Swagger Aggregator in advanced mode.

The advanced configuration allows managing how the swagger API 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 API 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.
Below are reported the properties that can be configured and how they can be employed to customize the Swagger Aggregator functionalities.

prefix#

Use prefix to add to all paths a prefix. This feature may be useful when using multiple API Gateway or when having a custom reverse proxy before your project.

Example#

prefix: '/your-prefix'

urlsBefore and urlsAfter#

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

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.

Example#

"urlsBefore":[
{
"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"
}
]

subswaggers#

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

There are many reasons to enable this feature, although they are usually such to cluster different endpoints under specific tags or to group routes so that they can be encapsulated into other projects.

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,that can be used as a handle in the urlsBefore to select which group should be exposed in other projects swaggers, and can include the following properties:

  • name: represents the name associated to 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.
    In order 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.

Example#

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