OpenAPI 3.0 tutorial overview

In the Swagger tutorial, I referenced an OpenAPI specification document without explaining much about it. You simply plugged the document into a Swagger UI project. In this section, we’ll dive more deeply into the OpenAPI specification. Specifically, we’ll use the same Mashape Weather API that we’ve been using throughout other parts of this course as the content for our OpenAPI document.

General resources for learning the OpenAPI specification

Learning the OpenAPI specification will take some time. As an estimate, plan about a week 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 about 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, 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.

How my OpenAPI/Swagger tutorial is different

Rather than try to reproduce the material in the guides or specification, in my OpenAPI/Swagger tutorial here, I give you a crash course in manually creating the specification document. I use a real API for context, and also provide detail about how the specification fields get rendered in Swagger UI.

Swagger UI is one of the most popular display frameworks for the OpenAPI specification. (The spec alone does nothing — you need some tool that will read the spec’s format and display the information.) There are many display frameworks that can parse and display information in an OpenAPI specification document (just like many component content management systems can read and display information from DITA files).

However, I think Swagger UI is probably the best tool to use when rendering your specification document. Swagger UI is sponsored by SmartBear, the same company that is heavily invested in the OpenAPI initiative and which develops Swaggerhub. Their tooling will almost always be 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.


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 spec, but the spec was later changed to OpenAPI to reinforce the open, non-proprietary nature of the standard. Now Swagger refers to API tooling, not the spec. People 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 this initiative is driven by the Linux Foundation. The OpenAPI spec’s development is driven by many companies and organizations.
  • The Swagger YAML file that you create to describe your API is called the “OpenAPI specification document” or the “OpenAPI document.”

Now that I’ve cleared up those terms, let’s continue. (For other terms, see the glossary.)

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 here. It probably won’t mean much at first, but 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.

Terminology to Describe JSON/YAML

The specification document in my OpenAPI tutorial uses YAML, 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 APIHandyman’s take on JSON vs YAML), so I’ve used YAML exclusively here. You will see that the spec 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.)

Note that YAML refers to data structures with 3 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 spec 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 synonyms. In the description for each field, the spec frequently refers to the field as a property, so I’m not sure why they chose to use “field” in subheadings and column titles.

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 that looks like in JSON:

  "demographics": [

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

Follow the OpenAPI tutorial

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

Note that the spec alone does nothing with your content. Other tools are required to read and display the spec document, or to generate client SDKs from it.

My preferred tool for parsing and displaying information from the specification document is Swagger UI, but many other tools can consume the OpenAPI document and display it in different ways. See the list of tools on Swagger here. Consider the screenshots from Swagger UI as one example of how the fields from the spec might be rendered.

You can see OpenAPI spec rendered with Swagger UI in 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, you can use APIMATIC to convert it automatically. You can also use APIMATIC to transform your specification document into a number of other outputs, such as RAML, Postman, or API Blueprint.

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.

58% Complete

58/94 pages complete. Only 36 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.

Subscriber count: 4,285