Before diving into the first step of the OpenAPI tutorial here, read the OpenAPI tutorial overview to get a sense of the scope of this tutorial. In brief, this OpenAPI tutorial is unique in the following ways:
There are 8 objects at the root level in the OpenAPI 3.0 spec. There are many nested objects within these root level objects, but at the root level, there are just these objects:
By “root level,” I mean the first level in the OpenAPI document. This level is also referred to as the global level, because some object properties declared here (namely
security) are applied to each of the operation objects unless overridden at a lower level.
The whole document (the object that contains these 8 root level objects) is called an OpenAPI document. The convention is to name the document openapi.yml.
“OpenAPI” refers to the specification; “Swagger” refers to the tooling (at least from Smartbear) that supports the OpenAPI specification. For more details on the terms, see What Is the Difference Between Swagger and OpenAPI?
As you work on your specification document, use the online Swagger Editor. The Swagger Editor provides a split view — on the left where you write your spec code, and on the right you see a fully functional Swagger UI display. You can even submit requests from the Swagger UI display in this editor.
Note that the Swagger Editor will validate your content in real-time, and you will probably see validation errors until you finish coding the specification document.
I usually keep a local text file (using Atom editor) where I keep the specification document, but I work with the document’s content in the online Swagger Editor. When I’m done, I copy and save the content back to my local file. The Swagger Editor caches the content quite well (just don’t clear your browser’s cache).
Start your openapi.yml file by adding each of these root level objects:
openapi: info: servers: paths: components: security: tags: externalDocs:
In the following sections, we’ll proceed through each of these objects and document the Mashape Weather API. Tackling each root-level object individually helps reduce the complexity of the spec.
components is more of a storage object for schemas defined in other objects, but to avoid introducing too much at once, I’ll wait until the
components tutorial to fully explain how to reference a schema in one object and add a reference pointer to the full definition in
In the openapi, indicate the version of the OpenAPI spec to validate against. The latest version is
3.0 was released in July 2017, so much of the information and examples online, as well as supporting tools, often relate to 2.0.
In the Swagger UI display, an “OAS3” tag appears to the right of the API name.
If your spec doesn’t validate, the Swagger UI display often won’t load the content or will show an error. For example, if you have an incorrect indentation in your YAML syntax, an error message might appear that indicates a
bad indentation of a mapping entry. You can click the Error button in the lower right to see more information.
Clicking this error button takes you to
https://online.swagger.io/validator/debug?url=/learnapidoc/docs/rest_api_specifications/openapi_weather.yml, showing you which document the online Swagger validator is attempting to validate and the error. You can also open up the JS console to get a little more debugging information (such as the column where the error occurs).
The online Swagger Editor provides these messages in the UI, so you probably won’t need to use Swagger UI’s error validation messaging to troubleshoot errors.
57/92 pages complete. Only 35 more pages to go...
If you would like to contribute back to say thank you for the API documentation course, click the Donate button below. Alternatively, to contribute content, such as a tutorial or a new section, contact me with your ideas. You can also submit a pull request in the GitHub repo to make your contribution. Even if you want to just fix a typo or add a sentence here and there, it's always welcome.
Get new posts delivered straight to your inbox.
© 2017, Tom Johnson