You may not have heard of the Open API specification (OAS), but you may have heard of Swagger. Basically, Swagger is a way of specifying your APIs. You can use it for designing your api, generating documentation, and even for generating the code or the API gateway. The OAS is the next evolution of the Swagger specification. And no, the name OAS has nothing to do with the term HATEOAS although I suppose you could specify an API in OAS that follows the HATEOAS principle... Confused yet? Good! Here's a little history:
History
In November 2015, a company called SmartBear donated the Swagger specification to the newly-forming Open API Initiative. This specification was renamed the Open API Specification (OAS) on January 1st, 2016 and moved to a new github repo. At that time, the Swagger spec was version 2.0. That's why the current Open API specification is version 2.0 even though there was technically no OAS v1.0. Construction on 3.0 started around that time too, and is still ongoing.
How we Use Swagger at 1904labs
We have been using Swagger for several projects to design and document our APIs. One of the projects involved building a new API from the ground up. After establishing the workflow for that project, we used the workflow to infer what endpoints we needed for the API. We then wrote up a Swagger doc to more specifically define each API endpoint. For implementation of the API, we decided not to use any code generation due to flexibility concerns, but with the Swagger doc as a reference, construction went smoothly and quickly. Writing the Swagger doc up front forced us to think about many details that may otherwise have been overlooked or that may have come up later in the process as a clarification question. As part of our build pipeline, we send the swagger docs from each of our APIs to Akana, an API gateway and portal, which uses the swagger docs to catalog each API, registering new ones and updating existing ones if there are changes. We will probably be one of the earlier adopters of the OAS 3.0 when it is released, since we are looking forward to taking advantage of some of the new features, such as more granular server specification.
Please Note
At the time of this writing, the Open API Specification version 3.0 is still under construction. The following information may therefore be subject to change.
That being said, major features in 3.0 seem to now be locked in
Superficial Updates (renames, etc)
Patterned Objects are now called Specification Extensions
These are those custom fields you can specify with the "x-" prefix. The most popular is probably the "x-swagger-router-controller" field. docs
'swagger' field is now 'openapi'
Try to contain your surprise. Instead of a "swagger" field in your root object to specify verson, its renamed to "openapi", and there's now a "patch" number tacked on the end of the version.
For example:
"swagger":"2.0"
is now
"openapi":"3.0.0"
docs
Major Updates: New Objects
Server Objects and Host Templates
Instead of having "host" and "basePath" fields at the top of our swagger doc, we can now specify an array of servers that will handle requests. Got a different server for dev, test, and prod? I hope you do, and now you can specify that here. Moreover, you can specify this array of servers at the root level of your api, the path level, or the operation level! And that's not all, folks. Each server url is now potentially a path template, enabling you to specify things like subdomains and basePaths. docs
Component Objects
Instead of having "definitions", "responses", "securityDefinitions", and "parameters" fields at the root level, there's a "components" field that contains them. This new Components Object holds not only those payload, response, security, and param definitions, but also new request, response header, link, and callback definitions. docs
Content Objects
This is probably the change that most people will notice. This new object resides in Request Body and Response objects. They are a list of content types, each of which now contain the schema of the object, if applicable. Consequently, these replace the schema objects that were previously directly under the Request objects. They also render unnecessary the "consumes" and "produces" fields at the root level. docs
Callback Objects
Need to specify who to call after your user makes a request? docs
Link Objects
What if an operation depends on the response payload of another? Now you can link them. docs
For more information on callbacks and links, check out this article.
Flow Objects
This is used in the Security Definitions Object to specify your OAuth flow types. docs
Request Body Objects
As its name implies, this describes the request's body. It is optionally included in the Operations Object. This used to be specified in either a "Body" or "Form" parameter type. Those parameter types no longer exists since a body really isn't a parameter (e.g. you can have more than one param in a request, but only one body). docs
Updates to Existing Objects
Root Fields
To summarize what's above:
- removed host, basePath, schemes, consumes, produces, definitions, parameters, responses, and securityDefinitions
- added servers and components
- kept info, paths, security, externalDocs
Info Object
For those markdown connoisseurs out there, you may be glad (or infuriated?) to know that the markdown used in the description field has been changed from GFM syntax to CommonMark. The rest of us may be slightly more interested that the termsOfService should now just be a link to the terms of service rather than trying to cram all your TOS text into the field itself. docs
Path Item Objects
Now you can add a summary and/or description to each path which will apply to all operations at that path.
Added fields:
- summary
- description
- servers
Operation Objects
The spec now supports the Trace operation. In case you're not familiar with that, calling trace will send back all the request information. Trace is useful if you are chaining your request through, say, a proxy, and you want to see exactly what is being received by the API server.
And as previously mentioned, added optional "servers" and "requestBody" fields and removed "consumes" and "produces". docs
Parameter Objects
Added a "Cookie" parameter type for passing cookie values. As mentioned, removed "Body" and "Form" param types.
Added a "deprecated" boolean field. In 2.0 you could only mark an operation as deprecated, but now you can mark a specific parameter as deprecated. docs
Example Object
Wherever you previously saw the example object, you can now optionally put "examples" instead to specify an array of examples instead of just a single one. docs
Schema Objects
Added "oneOf", "anyOf", and "not", as well as a "deprecated" boolean field. docs
Security Definition Object
Added those flow objects mentioned earlier, and that's about it so far. docs
Conclusion
This next version adds some welcome flexibility to the spec without too much added complexity. I'm looking forward to seeing it released into the wild. If you want a more in-depth treatment of the differences between 2.0 and 3.0, check out this excellent article on the structural changes and its follow-up article on parameters.
Updates
You can join the Open API Initiative LinkedIn Group here.
The release of the 3.0 spec is now scheduled for February 28th!
