What is OpenAPI?

The purpose of my article is a short introduction to OpenAPI and why it sometimes is called Swagger Specification. I would like to provide you guidance on your first steps in automated documentation.

Glad you asked…so here’s the break-down. In 2009, there was an English dictionary and API provider called Wordnik. Writing documentations of the API for every endpoint was extremely frustrating for developers. Therewith the need for an automated solution was huge. The technical co-founder of the dictionary site Wordnik – Tony Tam – had the idea of a simple structure to make automated writing of documentations possible and that is why he started with the first specification of API endpoints.

Thanks to this idea by Tony Tam and combined with a concept for the user interface by Ayush Gupta and code implementation by Ramesh Pidikiti and Zeke Sikilianos they ended up with the project name Swagger. So the Swagger API project was born and went Open Source in September 2011.

Using automation tools is not only to speed up your workflows or organisational stuff it is great for documentation too. Seriously, automation can help you to write documentations with more fun.

Swagger Specification vs. OpenAPI

The main benefit of Swagger API was an interactive user interface for end users.

Swagger automates the documentation out of the OpenAPI specification. It easily generates a UI for customers to understand the functionality of the API and additionally the customers are able to test the API endpoints. The Community Project Swagger was growing very fast because people liked the idea of automating API documentations based on an easy to understand structure.

In 2015 SmartBear acquired Swagger and Tony Tam joined the company as head of products for Swagger. In the same Year in November SmartBear announced that it was helping to create a new organization, under the sponsorship of the Linux Foundation, called the Open API Initiative where the big players Google, IBM and Microsoft were founding members.

On January 1st in 2016 the Swagger specification was renamed to OpenAPI. The specification itself wasn’t changed but it was an important step to separate the API description from the automation tools. Together with this change the Swagger version Number 2.0 became the first version of OpenAPI in Version 2.0.

Nowadays on one hand there is the OpenAPI Specification also known as Swagger specification and on the other hand the Swagger online tools maintained by SmartBear.

In July 2017 the new Version 3.0 of OpenAPI was published and this was an important step for this community project as it was the first big release after the separation in 2016.

Documentations automated by OpenAPI

For defining your API you can use YAML or JSON as data serialization language.

Based on your preferences you can specify your API easily and generate the documentation of methods, parameters and models automatically. This helps to keep the documentation, client libraries, and source code in sync.

You can find lots of different solutions based on the OpenAPI specification. You can use the Swagger Editor for designing, describing your API or SwaggerHub to work together with a whole team on your documentation. If you prefer an in-house solution „Spectacle“ might be your tool. With Spectacle you can generate a static website with node.js and a basic CLI.

OpenAPI structure

You can find some example specification in the references of this article but let me introduce you to the basic structure of OpenAPI.

Openapi, info, servers, paths, components, security, tags and externalDocs are the basic structure elements of OpenAPI. If you want to get into the details of each object you can find a great tutorial explaining the whole OpenAPI specification in the references.

As you thought, you can define the OpenAPI Version Number, some descriptions, the licence and some other info of your API easily in the head of your YAML file.

openapi: "3.0.1"
info:
  version: 1.0.0
  title: Some amazing new Product
  license:
    name: MIT

Now it’s getting even more interesting. with servers you can define the base url for your API.
servers:
  - url: http://petstore.swagger.io/v1
  - description: LIVE Server

You can add more than one server to this object. Maybe you want to add your development server, some testing area or a new version to this list. It’s on you to help customers with this information.

And here is the most important part of OpenAPI the path object.

paths:
  /weather:
    get:
      tags:
      - Current Weather Data
      summary: "Call current weather data for one location"
      description: "Access current weather data for any location on Earth including over 200,000 cities! Current weather is frequently updated based on global models and data from more than 40,000 weather stations."
      operationId: CurrentWeatherData
      parameters:
      - name: q
        in: query
        description: "**City name**. *Example: London*. You can call by city name, or by city name and country code. The API responds with a list of results that match a searching word. For the query value, type the city name and optionally the country code divided by comma; use ISO 3166 country codes."
        schema:
          type: string

For many reasons the OpenAPI specification allows you to structure your YAML document effectively. In „components“ you can store re-usable definitions that might appear in multiple places in your specification document.

The purpose of my article was to give you a short introduction to OpenAPI and a quick overview on the way you can structure your documentation. Since APIs as solutions are getting more and more important, having a good and automated documentation of your API makes you faster and your customers happy 😁. Don’t forget - the automated documentation is great however you still can design new API endpoints with that tool as well.