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
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.
Once known as Vendor Extensions, these Specification Extensions can be created by anyone, don’t be fooled by their original name.
To add a custom property with an OpenAPI definition file you only need to prefix its name by
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
info section with a custom property is valid:
Extensions are not only meant to be atomic properties, they can also be objects:
Note that sub-properties names do not need to be prefixed with
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
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).
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.