Search results

OpenAPI 3.0 tutorial overview

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.

In this section, we’ll dive deeply into the OpenAPI specification. We’ll use the same OpenWeatherMap API that we’ve been using throughout other parts of this course as the content for our OpenAPI document. Using this API, we’ll create a valid OpenAPI specification document and then render it into interactive documentation using Swagger UI.

General resources for learning the OpenAPI specification

Learning the OpenAPI specification will take some time. As an estimate, plan about two weeks of immersion, working with a specific API in the context of the specification before you become comfortable with it. As you learn the OpenAPI specification, use the following resources:

  • Sample OpenAPI specification documents. These sample specification documents provide a good starting point as a basis for your specification document. They give you a big picture of the general shape of a specification document.
  • Swagger user guide. The Swagger user guide is more friendly, conceptual, and easy to follow. It doesn’t have the detail and exactness of the specification documentation on GitHub, but in many ways, it’s clearer and contains more examples.
  • OpenAPI specification documentation. The specification documentation is technical and takes a little getting used to, but you’ll no doubt consult it frequently when describing your API. It’s a long, single page document to facilitate findability through Ctrl+F.

There are other Swagger/OpenAPI tutorials online, but make sure you follow tutorials for the 3.0 version of the API rather than 2.0. Version 3.0 was released in July 2017. 3.0 is substantially different from 2.0. (Version 3.0.2 was released in December 2017 and makes minor improvements to 3.0. Note that whenever I refer to 3.0, I’m referring to 3.x, meaning any incremental dot release from the 3.0 line.)

How my OpenAPI/Swagger tutorial is different

You can find many Swagger tutorials online. What makes mine different? Besides the end-to-end walkthrough using the OpenAPI 3.0 (rather than 2.0) version of the spec, and using an actual API for context, I also show how OpenAPI fields map to the Swagger UI display. Specifically, I demonstrate how and where each of the OpenAPI fields gets displayed in Swagger UI.

Granted, many other display frameworks can parse and display information in an OpenAPI specification document, but Swagger UI is one of the most popular. Swagger UI is sponsored by SmartBear, the same company that is heavily invested in the OpenAPI initiative and which develops Swaggerhub. Their tooling is almost always in sync with the latest spec features. Swagger UI an actively developed and managed open-source project.

By showing you how the fields in the spec appear in the Swagger UI display, I hope the specification objects and properties will take on more relevance and meaning. Just keep in mind that Swagger UI’s display is just one possibility for how the spec information might be rendered visually.

Terminology for Swagger and OpenAPI

Before continuing, I want to clarify a few terms for those who may be unfamiliar with the OpenAPI/Swagger landscape:

  • Swagger was the original name of the OpenAPI spec, but the spec was later changed to OpenAPI to reinforce the open, non-proprietary nature of this standard. Now, “Swagger” refers to API tooling that supports the OpenAPI spec, not the spec itself. People still often refer to both names interchangeably, but “OpenAPI” is how the spec should be referred to.
  • Smartbear is the company that maintains and develops the open source Swagger tooling (Swagger Editor, Swagger UI, Swagger Codegen, and others). They do not own the OpenAPI specification, as the Linux Foundation drives this initiative. The OpenAPI spec’s development is driven by many companies and organizations.
  • The “OpenAPI specification document” or “OpenAPI document” is the Swagger YAML file that you create to describe your API.

For other terms, see the API Glossary.

Let’s clear up some additional descriptors around JSON and YAML as well. The specification document in my OpenAPI tutorial uses YAML (which I introduced briefly here), but it could also be expressed in JSON. JSON is a subset of YAML, so the two are practically interchangeable formats (for the data structures we’re using). Ultimately, though, the OpenAPI spec is a JSON object. The specification notes:

An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format. (See Format)

In other words, the OpenAPI document you create is a JSON object, but you have the option of expressing the JSON using either JSON or YAML syntax. YAML is more readable and is a more common format (see API Handyman’s take on JSON vs YAML for more discussion), so I’ve used YAML exclusively here. You will see that the OpenAPI specification documentation on GitHub always shows both the JSON and YAML syntax when showing specification formats. (For a more detailed comparison of YAML versus JSON, see “Relation to JSON” in the YAML spec.)

YAML refers to data structures with three main terms: “mappings (hashes/dictionaries), sequences (arrays/lists) and scalars (strings/numbers)” (see “Introduction” in YAML 1.2). However, because the OpenAPI spec is a JSON object, it uses JSON terminology — such as “objects,” “arrays,” “properties,” “fields,” and so forth. As such, I’ll be showing YAML-formatted content but describing it using JSON terminology.

So that we’re on the same page with terms, let’s briefly review.

Each level in YAML (defined by a two-space indent) is an object. In the following code, california is an object. animal, flower, and bird are properties of the california object.

  animal: Grizzly Bear
  flower: Poppy
  bird: Quail

Here’s what this looks like in JSON:

  "california": {
    "animal": "Grizzly Bear",
    "flower": "Poppy",
    "bird": "Quail"

The specification often uses the term “field” in the titles and table column names when listing the properties for a specific object. (Further, it identifies two types of fields — “fixed” fields are declared, unique names while “patterned” fields are regex expressions.) Fields and properties are used synonymously in the OpenAPI spec.

In the following code, countries contains an object called united_states, which contains an object called california, which contains several properties with string values:

      animal: Grizzly Bear
      flower: Poppy
      bird: Quail

In the following code, demographics is an object that contains an array.

 - population
 - land
 - rivers

Here’s what the above code looks like in JSON:

  "demographics": [

Hopefully, those brief examples will help align us with the terminology used in the tutorial.

Start by looking at the big picture

If you would like to get a big picture of the specification document, take a look at the 3.0 examples here, specifically the Petstore OpenAPI specification document. It probably won’t mean much at first, but try to get a sense of the whole before we dive into the details. Look at some of the other samples in the v.3.0 folder as well.

Follow the OpenAPI tutorial

The OpenAPI tutorial has eight steps. Each step corresponds with one of the root-level objects in the OpenAPI document.

You don’t have to create the specification document in this order; I’ve merely chosen this order to provide more of a specific path and series of steps to the process.

In the following sections, we’ll proceed through each of these objects one by one and document the OpenWeatherMap current API. Tackling each root-level object individually (rather than documenting everything at once) 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 (using $ref) that points to the full definition in components.

With each step, you’ll paste the object you’re working on into the Swagger Editor. The right pane of the Swagger Editor will show the Swagger UI display. (Remember that the specification document alone does nothing with your content. Other tools are required to read and display the spec document.)

Later, when I talk more about publishing, I’ll explain how to configure Swagger UI with your specification document as a standalone output. For our sample OpenWeatherMap API, you can see the OpenAPI spec rendered by the Swagger UI at the following links:

Migrating from OpenAPI 2.0 to 3.0

If you have an existing specification document that validates against version OpenAPI 2.0 and you want to convert it to OpenAPI 3.0 (or vice versa), you can use APIMATIC’s Transformer to convert it automatically. (You can also use APIMATIC to transform your specification document into many other outputs, such as RAML, API Blueprint, or Postman.)

To see the difference between the 2.0 and the 3.0 code, you can copy these code samples to separate files and then use an application like Diffmerge to highlight the differences. The blog has a nice post that provides A Visual Guide to What’s New in Swagger 3.0.

Helpful resources

As you embark on creating an OpenAPI specification file, you might find the recording of Peter Gruenbaum’s Swagger/OpenAPI presentation to the STC Puget Sound chapter helpful, as well as his Udemy course.

Brace yourself — this is where you’ll find out if you’re cut out for API technical writing.

65% Complete

65/150 pages complete. Only 85 more pages to go.


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