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
As promised in my previous post, I’ll show you how to write API definition with OpenAPI Specification (fka Swagger Specification) format. This tutorial will be composed of several posts:
- Part 1: Introduction
- Part 2: The basics
- Part 3: Simplifying specification file
- Part 4: Advanced data modeling
- Part 5: Advanced input and output modeling
- Part 6: Defining security
- Part 7: Documentation
- Part 8: Splitting specification file
- Part 9: Extending the OpenAPI specification (coming soon)
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).
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…
…to the same definition in YAML:
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.