Step 1: The openapi object (OpenAPI tutorial)
- OpenAPI tutorial overview
- The root-level objects in OpenAPI spec
- Swagger Editor
- Step 1: Add root-level objects
- The openapi object
- Validator errors
OpenAPI tutorial overview
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:
- This OpenAPI tutorial shows the spec in context of a simple weather API introduced earlier in this course.
- The OpenAPI tutorial shows how the spec information gets populated in Swagger UI.
- The OpenAPI tutorial is a subset of the information in both the OpenAPI specification and the OpenAPI specification commentary.
- The OpenAPI tutorial covers the 3.0 version of the OpenAPI spec, which is the latest version.
The root-level objects in OpenAPI spec
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).
Step 1: Add root-level objects
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 OpenWeatherMap current 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
The openapi object
In the openapi, indicate the version of the OpenAPI spec to validate against. The latest version is
3.0 was released in July 2017, and 3.0.1 was releasein December 2017. Much of the information and examples online, as well as supporting tools, often focus only on 2.0. Even if you’re locked into publishing in a 2.0 tool or platform, you can code the spec in 3.0 and then use a tool such as APIMATIC Transformer to convert the 3.0 spec to 2.0. You can also convert a spec from 2.0 to 3.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.
59/96 pages complete. Only 37 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.
I'd Rather Be Writing Newsletter
Get new posts delivered straight to your inbox.