Writing OpenAPI (Swagger) Specification Tutorial Series - Part 9

Extending the OpenAPI specification

By Arnaud Lauret, February 19, 2017

This is the end, my OpenAPI friends, the end. The end? Not really. This last part of the OpenAPI tutorial is a new beginning. With previous parts we have learned to master the OpenAPI specification but there’s a last thing to learn to unleash its full power: extensions. This format is easily extensible, it allows to add custom data within an API description. But for what purposes? Let’s have a glimpse of these extensions endless possibilities.

Writing OpenAPI (Swagger) Specification Tutorial Series

This tutorial teaches everything about the OpenAPI 2.0 Specification (fka. as Swagger), most of what you’ll read here can still be applied on version 3.

If you’re a bit lost in the specification (version 2 or 3), take a look at the OpenAPI Map:

In this final part we’ll learn how to extend the OpenAPI specification to add custom data and most important, we’ll discover why we would do that.

One size may not fit all

After working for a while with the OpenAPI format, you WILL want to add other data into you API descriptions, this is your destiny. Fortunately, the creator of the format had foreseen that:

While the Swagger Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
OpenAPI Specification

Once known as Vendor Extensions, these Specification Extensions can be created by anyone, don’t be fooled by their original name.

Custom property

To add a custom property with an OpenAPI definition file you only need to prefix its name by x-:

x-<what you want>: <value>

Here’s a custom property x-custom-info in the info section of an OpenAPI file:

info:
  version: 1.0.0
  title: x-tended OpenAPI Specification
  description: An OpenAPI specification containing custom data
  x-custom-info: Here's some custom information

If a standard Swagger/OpenAPI parser encounters such property, it will ignore it because it’s prefixed with x-. This info section with a custom property is valid:

Custom object

Extensions are not only meant to be atomic properties, they can also be objects:

info:
  version: 1.0.0
  title: x-tended OpenAPI Specification
  description: An OpenAPI specification containing custom data
  x-custom-info:
    comment: Here's some custom information
    authors:
      - name: John Doe
        email: [email protected]
      - name: Jane Doe
        email: [email protected]

Note that sub-properties names do not need to be prefixed with x-.

Extensions almost anywhere

These custom data structures can be added almost anywhere in the specification. You can test if a location is ok by simply adding your extension where you want within the online editor and see if the validator complains or not.

You can also take a look at my visual documentation to check if the location you want to use allows extension or not:

Here’s an example using various location (non-exhaustive example):

swagger: '2.0'

x-root: some custom root data

info:
  version: 1.0.0
  title: x-tended OpenAPI Specification
  description: An OpenAPI specification containing custom data
  x-custom-info:
    comment: Here's some custom information
    authors:
      - name: John Doe
        email: [email protected]
      - name: Jane Doe
        email: [email protected]

paths:
  /resources:
    get:
      description: gets some resource
      responses:
        200:
          description: everything is ok
          x-custom-response-data: I told you everything was really OK!
          schema:
            type: array
            items:
              $ref: "#/definitions/Resource"

definitions:
  Resource:
    x-custom-definition-data: some.dummy.class.Resource
    properties:
      data:
        description: some data
        type: string
        x-custom-property-data: More blah blah about this property

Why customizing the OpenAPI specification?

So, adding custom information within an OpenAPI specification file is fairly easy. But the question is less about the how and more about the why. Why would you add custom data to your OpenAPI files?

You can use some extensions provided by open source or commercial tools or create your own. You can simply add custom data without processing them for documentation purpose or use these informations to generate documentation, client code, server code or tests or even configure some tools.

Let’s see some examples.
nb: This post is not a sponsored one.

Example 1: Documentation

Gelato, the Mashape Developer Portal solution, uses the x-gelato-group extension to group operations in the portal navigation.

Of course, as an OpenAPI expert you would have use tags to do that. Beware to not reinvent the wheel when creating your extensions.

Example 2: Client code generation

API Matic, a SDK/DX kits generator uses extension ton control SDK generation.

Example 3: Server code generation

Swagger Node, a node module which help to build API implementation with a design first approach uses a x-swagger-router-controller extension to link an API endpoint to its controller implementation.

Example 4: API gateway configuration

Not only the AWS API gateway allows to import a Swagger/OpenAPI file but it also provides a complete set of extensions to configure how the API is linked to backend systems (like lambda).

Conclusion

This post concludes the OpenAPI/Swagger specification tutorial. You master now every single aspect of the OpenAPI specification and with this last post I hope to have given you some ideas to be creative to include this format in each step of the API lifecycle.