Writing OpenAPI (Swagger) Specification Tutorial Series - Part 1

Introduction

By Arnaud Lauret, March 2, 2016

Previously in the APIverse…
Since I started my Swagger journey, there have been some changes. The Swagger Specification has been donated to the newly created OpenAPI Initiative under the Linux foundation and is reborn as the OpenAPI Specification. Therefore, my Swagger Journey will become an OpenAPI Specification (fka Swagger Specification) Journey.

This first part explains what is the OpenAPI Specification, why you will use it and what tools you can use to write these specifications.

Writing OpenAPI (Swagger) Specification Tutorial Series

This tutorial teaches everything about the OpenAPI 2.0 Specification (fka. as Swagger), most of what you’ll read here can still be applied on version 3.

If you’re a bit lost in the specification (version 2 or 3), take a look at the OpenAPI Map:

The OpenAPI Specification

The OpenAPI Specification is an API description format or API definition language. Basically, an OpenAPI Specification file allow you to describe an API including (among other things):

General information about the API
Available paths (/resources)
Available operations on each path (get /resources)
Input/Output for each operation

The Open API Specification’s specification can be found in the github repository of the Open API Initiative. This document describes every aspect of the Open API Specification. Even if this documentation is fairly easy to read, I was sometimes a little bit lost. So, based on this text specification, I have created the OpenAPI Map a visual documentation which can help to figure how a OpenAPI specification file is structured for people who are more visual like me.

Reading the specification is not mandatory to do this tutorial, you can dig into the specification as you discover it through this tutorial.

Why using an API definition language such as OpenAPI specification?

Using an API definition language such as OpenAPI specification helps to describe easily and quickly an API. It’s particularly useful when you’re in the design process of your API (cf. my first post in the series).

Being a simple text file, the OpenAPI specification file can be shared and managed within any VCS just like [code]/code.

Once written, OpenAPI specification file can also be used as:

source material for documentation
specification for developers
partial or complete code generation
and many other things…

Writing OpenAPI Specification

What can we use to write an OpenAPI Specification file?

You kids keep your noses clean, you understand? You’ll be hearing from me if you don’t! We ain’t gonna stand for any weirdness out here! Officer Dorf about OpenAPI Specification writing

JSON vs YAML

An Open API Specification file can be written either in JSON or YAML. But, if you intend to write and not generate this file, I urge you to do that in YAML as YAML is far more easy to write and read than JSON.

A picture is worth a thousand words, let’s compare a simple definition in JSON…

{
    "swagger": "2.0",
    "info": {
        "version": "1.0.0",
        "title": "Simple API",
        "description": "A simple API to learn how to write OpenAPI Specification"
    },
    "schemes": [
        "https"
    ],
    "host": "simple.api",
    "basePath": "/openapi101",
    "paths": {
        "/persons": {
            "get": {
                "summary": "Gets some persons",
                "description": "Returns a list containing all persons.",
                "responses": {
                    "200": {
                        "description": "A list of Person",
                        "schema": {
                            "type": "array",
                            "items": {
                                "properties": {
                                    "firstName": {
                                        "type": "string"
                                    },
                                    "lastName": {
                                        "type": "string"
                                    },
                                    "username": {
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

…to the same definition in YAML:

swagger: "2.0"

info:
  version: 1.0.0
  title: Simple API
  description: A simple API to learn how to write OpenAPI Specification

schemes:
  - https
host: simple.api
basePath: /openapi101

paths:
  /persons:
    get:
      summary: Gets some persons
      description: Returns a list containing all persons.
      responses:
        200:
          description: A list of Person
          schema:
            type: array
            items:
              required:
                - username
              properties:
                firstName:
                  type: string
                lastName:
                  type: string
                username:
                  type: string

YAML seems definitely more easy to write and read for humans. And almost every tool using OpenAPI specification files handle YAML. In last resort, you can easiliy convert YAML to JSON (and vice versa).

Editor

Even if an OpenAPI specification is a simple text file which can be edited with any text editor, it’s better to use a specialized one. The best available tool to write Open API Specification file is Swagger Editor. It’s a set of static file allowing you to write and validate Open API Specification in YAML and see a rendering of the written specification.

On the left pane, you write your API definition. On the right one you see a rendering of your definition and potential syntax errors.

The editor also provides useful snippets to guide you:

You can use the online version but you can also have your own editor instance on any http server. You just need to download the lastest build and serve it with an http server. Go to Swagger Editor Github repository for a complete how-to.

What about writing your first OpenAPI Specification?

We are now ready to proceed to Part 2 - The basics and write our first API definition using the Open API Specification.