Using OAS (Swagger) extensions with Stoplight

This week, we introduced the ability to modify your OAS export. You can use this feature to take advantage of OAS extensions.

Extensions are properties that start with x-, such as x-codegen, and allow you to describe extra functionaliy or settings that don't otherwise fit into the standard OAS specification.

Here is a quick GIF demonstrating how to add an x-foo extension to the info object of your OAS export:

There are a number of API related products that make use of extensions, such as AWS API Gateway, APIMatic, and Stoplight itself. You can view the extensions that Stoplight adds to your swagger by navigating to an API in the app, and then clicking Swagger + Stoplight extensions in the top right export dropdown.

Read more about OAS extensions @ https://github.com/OAI/OpenAPI-Specification/blob/master/guidelines/EXTENSIONS.md.

The JSON object you descibe in the OAS export section will be merged into the final object produced by our export process. At the moment, this feature only works with the Swagger JSON export (not YAML).

For Example

Let's say that you wanted to take advantage of some of the AWS API Gateway extensions. Take, for example, the x-amazon-apigateway-authorizer extension (described at the start of the linked gateway extensions article). In order to include this in your final OAS export, you would navigate to the OAS extensions top tab in the Stoplight API design module, and describe the following object:

{
  "securityDefinitions" : {
    "apikey" : {
      "x-amazon-apigateway-authtype" : "oauth2", 
      "x-amazon-apigateway-authorizer" : {      
        "type" : "token",                       
        "authorizerUri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:account-id:function:function-name/invocations",
        "authorizerCredentials" : "arn:aws:iam::account-id:role",
        "identityValidationExpression" : "^x-[a-z]+",
        "authorizerResultTtlInSeconds" : 60
      }
    }
  }
}

This would extend your the "apikey" security scheme to include the custom AWS extensions, in the final export.

These same principles apply to all extensions. In fact, since the object is simply merged into your final export, you can use this feature to add any properties you want - not just extensions.

Making Sure It Works

To check and see what your final OAS (Swagger) object will look like, simply click "Save" at the bottom of the extensions editor, and then click the export -> OAS (Swagger) 2 .json button in the top right of the Stoplight app. You should see your extension object, and it's properties, merged into your final OAS export.


Sign up for Stoplight today over at https://app.stoplight.io/register!