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.

Writing OpenAPI (fka Swagger) Specification tutorial

This tutorial is composed of several posts:

If you’re a bit lost in the specification, take a look at my visual documentation:

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

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 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


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": [
    "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"

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

  - https
host: simple.api
basePath: /openapi101

      summary: Gets some persons
      description: Returns a list containing all persons.
          description: A list of Person
            type: array
                - username
                  type: string
                  type: string
                  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).


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?

YAML + editor. You've been warned.

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