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

FAQs

How can I change the title?​

The title is related to the documentation version and it corresponds to the title key in the info object of the Open Api specification document. To change it, you have to edit the Swagger Aggregator configuration.

Example of swagger-aggregator.json:

{
  "title": "Your Custom Title"
}

How can I change the grey badge next to the title?​

The grey badge next to the title is related to the documentation version and it corresponds to the version key in the info object of the Open Api specification document. To change it, you have to edit the Swagger Aggregator configuration.

Example of swagger-aggregator.json:

{
  "version": "1.0"
}

Those information are related to the info object of the Open Api specification document.

To change it, you have to edit the Swagger Aggregator configuration: you have to add the info key in the baseSwagger object and make sure to write a compliant Open API info object

Example of swagger-aggregator.json:

{
  "baseSwagger": {
    "swagger": "2.0",
    "consumes": [
      "application/json"
    ],
    "produces": [
      "application/json"
    ],
    "securityDefinitions": {
      "APISecretHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "secret"
      }
    },
    "info": {
      "termsOfService": "<termsOfService-link>",
      "license": {
        "name": "License Name",
        "url": "<license-link>"
      },
    }
  }
}
danger

If you edit the baseSwagger object, you have to include ALL the information needed or the configuration will be incorrect.

How can I change the route to which is exposed the API Portal?​

By default, the API Portal is exposed on /documentations/api-portal. You can change it going to the Endpoints section:

  1. Delete the /documentations/api-portal endpoint
  2. Create a new endpoint with you custom route, with type Microservice and api-portal as microservice.

How can I use only one microservice to show the API Portal?​

If you already have the swagger-aggregator and the api-portal microservices on your project, you have to:

  1. Change the swagger-aggregator version and set the 3.7.0 or one above.
  2. Delete the api-portal microservice

Then go to the Endpoints section and:

  1. Delete the endpoint on which the API Portal is exposed.
  2. Create a new endpoint with the same route on which the API Portal was exposed, with type Microservice and swagger-aggregator as microservice.
  3. Edit the Rewrite Base Path of the endpoint just created and set it to /swagger
note

Using this option, you can't control the API Portal version. To see which version you are using, check the Changelog

How can I authenticate my endpoints with OAuth 2.0?​

To enable OAuth 2.0 authentication you need to edit the Swagger Aggregator configuration by adding inside the baseSwagger:

  1. the securityDefinition object configured with the correct Swagger 2.0 compliant
  2. the security array listing the security requirements

For example:

{
  "baseSwagger": {
    "swagger": "2.0",
    "security": [
      { 
        "oidc": ["openid"]
      }
    ],
    "securityDefinitions": {
      "oidc": {
        "authorizationUrl": "your-authorization-url",
        "flow": "accessCode",
        "scopes": {
          "openid": "openId scope",
        },
        "tokenUrl": "your-token-url",
        "type": "oauth2",
      },
    }
  }
}

How can I configure my OAuth 2.0 flow?​

caution

The following information are applicable to a Swagger Aggregator version greater or equal than 3.8.0 and an API Portal version greater or equal than 2.1.0.

To enable OAuth 2.0 authentication you need to edit the Swagger Aggregator configuration by adding at first level the oauthConfig object containing the desired swagger-ui OAuth 2.0 configuration.

For example:

{
  "baseSwagger": {
    "swagger": "2.0",
    "security": [
      { 
        "oidc": ["openid"]
      }
    ],
    "securityDefinitions": {
      "oidc": {
        "authorizationUrl": "your-authorization-url",
        "flow": "accessCode",
        "scopes": {
          "openid": "openId scope",
        },
        "tokenUrl": "your-token-url",
        "type": "oauth2",
      },
    }
  },
  "oauthConfig": {
    "clientId": "my-client-id",
    "usePkceWithAuthorizationCodeGrant": true,
    "scopes": ["openid"]
  }
}