OpenAPI tutorial step 1: The openapi object

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 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 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?

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.

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 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 components.

The openapi object

In the openapi, indicate the version of the OpenAPI spec to validate against. The latest version is 3.0.0.

openapi: "3.0.0"

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.

Validator errors

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.

Get new posts delivered straight to your inbox.

Subscriber count: 4,285