Introduction to OpenAPI (fka Swagger)

With the OpenAPI Specification you can describe and document your RESTful API. In the diagram bellow you can see wich tools can help you describing your API and support you in the general workflow.

World of OpenAPI

The blue box in the center is the main subject of this story. We talk about the green boxes a bit, the open source tools. The Pro Tools are not mentioned in this story.

In the title I use OpenAPI and in parentheses fka Swagger, I do this because till version 2 the Specification was named Swagger, from version 3.* on it’s named OpenAPI. The tools around the Specification are still named Swagger.

In the diagram below you can see an overview of the building blocks of the OpenAPI Specification. The green boxes are the mandatory fields and the orange ones are optional.

OpenAPI Object — fields

There are two ways of describing the OpenAPI Specification, you can write it directly in YAML or JSON, with the help of Swagger Editor or IDE Plugins. Or you can annotate your code and generate the OpenAPI Specification. Swagger Editor has on the right side an embedded Swagger UI.

You can use the online version of Swagger Editor here or you can install it via npm here.

For annotating your code here are some of the libraries listed, linked to the repositories:

• Java
• C#
• Node.js
• PHP
• Go
• Python Django
• Python Flask
• Spring

You can find a complete list here.

Now, I will go over the mandatory building blocks of the diagram above and also the optional one servers and give a brief explanation with an YAML example. You can find the very good and comprehensive documentation of the Specification here.

The first mandatory field is openapi, you need to pass the version of the OpenAPI Specification you want to use as a string. The actual version is 3.0.3

openapi: “3.0.3”

The next field info is also required, it accepts an object with the metadata about your API. The required fields are version and title. You can see all available fields here.

info: 
  version: 1.0.0 
  title: Swagger Petstore 
  license: 
    name: MIT
  description: Petstore API

A nice feature is that you can use Markdown in the description field that has only the text “Petstore API” above. OpenAPI uses CommonMark, you can read more about it here. You need to add | after description: and every following line has to have the same indentation.

description: |
 ## Petstore API
 
 | Syntax | Description |
 | — — — — — — | — — — — — — |
 | Header | Title |
 | Paragraph | Text |

The next field servers is optional and contains a list of connectivity information to the target servers. It accepts an array of objects. You could pass your test, stage, and live server here. The URL is the only required field of the server object, you can read more here.

servers: 
  — url: http://petstore.swagger.io/v1
    description: Live Server

The next field paths is mandatory at the heart of the specification, here you describe the endpoints of your API, you can read more about it here. Each path /{path} takes an Operation Object the only required field for this object is responses.

Below we describe a GET endpoint, that has one query parameter limit and is of type integer with an optional format int32, just one response with status 200 and JSON as content. You can find a list of all available data types and their formats here.

The operationId is a very interesting field for you if you like to use the OpenAPI generator.

If you describe the parameters field there are a few mandatory fields name, in and required. You can read more in the documentation here.

You can define a default in the responses field object that catches all not defined status codes. In the response object the description field is the only mandatory one, more in the documentation here.

paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      tags:
        - pets
      parameters:
        - name: limit
          in: query
          description: How many items to return at one time (max 100)
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: A paged array of pets
          headers:
            x-next:
              description: A link to the next page of responses
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pets"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

Nice, now you have a first working example, we already talked about three parts of the initial diagram of this story Swagger Editor, Annotation Libraries, and the OpenAPI Specification itself. There are two more parts we will talk about Swagger UI and Swagger Codegen.

The parts I explained are from the “hello world” example from the OpenAPI Github repository here, I only changed the version to the actual one.

The Swagger UI is a nice, modern-looking way of inspecting and testing your API. You can visit the online version here Swagger UI Petstore the tags you were specifying is the grouping for your endpoints in the UI.

Swagger UI

1. The HTTP Method you specified with get:
2. The path you specified, this one is slightly different then what we defined, here is a path parameter added, behind it, you see the summary
3. You see the description and optional field
4. A list of the specified parameters, it’s red marked as required and below the path parameter name you see the type integer and the format int64
5. With the Try it out button you can switch into a mode where you can send a curl request and see the response in the UI
6. The field gets validated againts the type and format that is specified
7. A list of responses and if specified the response structure

You can easily use the UI as an NPM package, I use it often to check the generated JSON after I annotated my code. You can open it from the command line with:

open-swagger-ui ./openapi.json — open # json
open-swagger-ui ./openapi.yaml — open # yaml

The URL to the UI is also something you can give to a Tester or someone who is not technically involved in the API.

The last part of our first diagram is Swagger Codegen, new implementation for version 3.* of the Specification OpenAPI Generator. You can generate a lot of clients, servers, documentation, schemas, and configs from your JSON or YAML file. You can see the impressive list here.

It can save you a lot of time generating code from your OpenAPI Specification file. If let’s say a none technical project manager defines the API with the Swagger Editor, the developer can generate the code for the frontend and/or backend from the definitions and if you integrate that into your workflow you always have up to date services etc and save time. A frontend developer for example can focus on the UI and doesn’t need to think about how to interact with the API.

I hope you find this story helpful and it answered some of the questions you might have. If there is something unanswered, you are welcome to write a comment.