Search results

Step 1: The openapi object (OpenAPI tutorial)

Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,000+ subscribers

I'm giving an API documentation workshop in Los Angeles, California, on January 23, 2020. Check it out on EventBrite and register today to receive a $100 early bird discount.

OpenAPI tutorial overview

Before diving into the first step of the OpenAPI tutorial here, read the OpenAPI tutorial overview (if you haven’t already) 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 eight 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 servers and security) are applied to each of the operation objects unless overridden at a lower level.

The whole document (the object that contains these eight 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?

Swagger Editor

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.

The Swagger Editor will validate your content in real-time, and you will see validation errors until you finish coding the specification document. Don’t worry about the errors unless you see X marks in the code you’re working on.

I usually keep a local text file (using Atom editor) where I keep the specification document offline, but I work with the document’s content in the online Swagger Editor. When I’m done working for the day, I copy and save the content back to my local file. Even so, the Swagger Editor caches the content quite well (just don’t clear your browser’s cache), so you probably won’t need your local file as a backup.

If you want to purchase a subscription to SwaggerHub, you could keep your spec content in the cloud (SwaggerHub has an editor almost identical to Swagger UI) associated with your personal login. SwaggerHub is the premium tooling for the open-source and free Swagger Editor.

Add the openapi object

Go to the Swagger Editor and go to File > Clear editor. Keep this tab open throughout the OpenAPI tutorial, as you’ll be adding to your specification document with each step.

Add the first root-level property for the specification document: openapi. In the openapi object, indicate the version of the OpenAPI spec to validate against. The latest version is 3.0.2.

openapi: "3.0.2"

Until you add more information in here, you’ll see error messages and notes such as “No operations defined in spec!” That’s okay — in the next step, you’ll start seeing more info.

3.0 was released on 2017-07-26, and 3.0.2 was released on 10-08-2018 (see Version History). 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.

Appearance in Swagger UI

There’s not much to the openapi object, and right now there’s not enough content for the spec to validate. But when you later render your specification document through the Swagger UI display, you’ll see that an “OAS3” tag will appear to the right of the API name.

On the backend, Swagger UI uses the 3.0.2 version of the spec to validate your content.

In the above screenshot, the “2.5” version refers to the version of the API here, not the version of the OpenAPI spec.

66% Complete

66/150 pages complete. Only 84 more pages to go.


Want to buy me lunch? Click the Donate button below to donate any amount through Paypal.