Join Wintertainment 2021 to share your stories, have fun, earn community badges, and more!

SwaggerHub Vendor Extensions

Last modified on December 07, 2021

SwaggerHub supports the following vendor extensions for OpenAPI.

Interactive documentation

x-example

Applies to: OpenAPI 2.0

Used to specify example values for path, query, header, and form parameters. These example values will be used to populate the "try it out" form in interactive API documentation.

parameters:
  - in: query
    name: q
    type: string
    description: Search string
    x-example: swagger    # <-------

x-tokenName

SwaggerHub On-Premise note: x-tokenName is supported since v. 1.18.8 for OpenAPI 2.0 and since v. 1.24 for OpenAPI 3.0.

The name of the token to be extracted from the OAuth 2.0 token endpoint response and subsequently used in the Authorization: Bearer TOKEN header. If not specified, SwaggerHub will use the standard access_token.

A typical example is the Google OAuth 2.0 flow, which returns an extra JWT id_token containing user identity information:

{
  "access_token": "...",
  "expires_in": 3599,
  "scope": "scope1 scope2",
  "token_type": "Bearer",
  "id_token": "....."
}

If your API uses Google id_token instead of access_token for authentication, add x-tokenName: id_token to the OAuth security scheme definition:

securityDefinitions:
  google_oauth:
    type: oauth2
    description: See https://developers.google.com/identity/protocols/OAuth2UserAgent
    flow: accessCode
    authorizationUrl: https://accounts.google.com/o/oauth2/v2/auth
    tokenUrl: https://www.googleapis.com/oauth2/v4/token
    x-tokenName: id_token    # <-------
    scopes: {}

Code generation

For a list of x- extensions supported by the code generator, see Swagger Codegen Vendor Extensions.

Integrations

Amazon API Gateway

x-amazon-apigateway-*

Contains API Gateway-specific information. For more information, see Amazon API Gateway Extensions in AWS documentation.

x-aws-api-id

Contains AWS ID of the associated API.

x-disabled-for-amazon-gateway

OpenAPI schema keywords not supported by AWS (such as example) are moved under the x-disabled-for-amazon-gateway extension.

Apigee Edge

x-apigee-id

Contains the name of the associated Apigee API proxy.

Azure API Management

x-azure-api-id

Contains Azure ID of the associated API.

IBM API Connect

x-ibm-configuration

Contains IBM-specific information. For more information, see IBM extensions to the OpenAPI specification in IBM documentation.

x-ibm-name

Contains an IBM ID of the associated API.

See Also

Interactive API Documentation
Generating Code
SwaggerHub Integrations

Highlight search results