OpenAPI Initiative's
OpenAPI Specification
Without the OpenAPI Specification (fka. Swagger Specification), my job would be a total nightmare. It is a machine readable API description format that I use when I design APIs, when reviewing API designs, documentating APIs, checking that implementation conforms to design and build implementation.
Related Posts
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.
Writing OpenAPI (Swagger) Specification Tutorial Series - Part 2
The basics
By Arnaud Lauret, March 2, 2016
After discovering what is the OpenAPI Specification format, it’s now time to write a first simple OpenAPI Specification file to learn the basics.
Writing OpenAPI (Swagger) Specification Tutorial Series - Part 3
Simplifying specification file
By Arnaud Lauret, March 19, 2016
After learning the basics and having written a little bit huge file for a so simple API, you may be concerned by what nightmare it could be to handle a bigger and more complex API. REST assured that the OpenAPI Specification (formerly Swagger Specification) format offers all means to write really small and simple specification files whatever the described API’s size and complexity.
Writing OpenAPI (Swagger) Specification Tutorial Series - Part 4
Advanced Data
By Arnaud Lauret, April 17, 2016
After learning how to simplify specification files, let’s start delving into the OpenAPI specification’s and discover how to describe a high accuracy API’s data model.
Writing OpenAPI (Swagger) Specification Tutorial Series - Part 5
Advanced Input And Output Modeling
By Arnaud Lauret, May 6, 2016
After learning how to create an accurate data model, we continue to delve into the OpenAPI specification’s and discover how to describe tailor made API’s inputs and outputs.
Writing OpenAPI (Swagger) Specification Tutorial Series - Part 6
Defining Security
By Arnaud Lauret, May 22, 2016
After mastering input and output modeling like a Jedi, let’s see how we can describe API’s security with the OpenAPI specification’s.
Writing OpenAPI (Swagger) Specification Tutorial Series - Part 7
Documentation
By Arnaud Lauret, June 12, 2016
Previous posts showed how to write a highly accurate description of an API interface contract with the OpenAPI specification. But an interface contract, no matter how brilliant, is nothing without some explainations. A fully documented OpenAPI specification file can provide some useful information and be used as a part of an API’s documentation.
Writing OpenAPI (Swagger) Specification Tutorial Series - Part 8
Splitting specification file
By Arnaud Lauret, August 2, 2016
With previous posts we have learned to produce an OpenAPI specification containing all OpenAPI specification subtleties. Some specification files may become quite large or may contain elements which could be reused in other APIs. Splitting a specification file will help to keep it maintainable by creating smaller files and also help to ensure consistency throughout APIs by sharing common elements.
Writing OpenAPI (Swagger) Specification Tutorial Series - Part 9
Extending the OpenAPI specification
By Arnaud Lauret, February 19, 2017
This is the end, my OpenAPI friends, the end. The end? Not really. This last part of the OpenAPI tutorial is a new beginning. With previous parts we have learned to master the OpenAPI specification but there’s a last thing to learn to unleash its full power: extensions. This format is easily extensible, it allows to add custom data within an API description. But for what purposes? Let’s have a glimpse of these extensions endless possibilities.
JQ and OpenAPI Series - Part 1
Using JQ to extract data from OpenAPI files
By Arnaud Lauret, January 15, 2020
Ever wanted to quickly find, extract or modify data coming from some JSON documents on the command line? JQ is the tool you’re looking for. In this 4 parts post series, you’ll discover why and how I use JQ with OpenAPI Specification files. But more important, you’ll get some basic and more advanced example of how to use JQ on any JSON document to get and modify JSON data as you want. In this first part we’ll focus on what is JQ, why I use it with OpenAPI files and we’ll learn how to invoke JQ and discover some of the many JQ filters that can be used to extract data from JSON.
JQ and OpenAPI Series - Part 2
Using JQ command line arguments, functions and modules
By Arnaud Lauret, February 3, 2020
Ever wanted to quickly find, extract or modify data coming from some JSON documents on the command line? JQ is the tool you’re looking for. In the previous part of this JQ and OpenAPI Series, we learned to invoke JQ and how to extract data from JSON documents using some of its many filters. Now we will discover how to build flexible and easily reusable JQ filters by creating functions and modules and also using command line arguments.
JQ and OpenAPI Series - Part 3
Modifying OpenAPI files with JQ
By Arnaud Lauret, June 28, 2020
Ever wanted to quickly find, extract or modify data coming from some JSON documents on the command line? JQ is the tool you’re looking for. Thanks to the two previous parts of this JQ and OpenAPI Series, we learned how to extract data from JSON (OpenAPI) files by discovering many filters, creating modules and using command line arguments. Now we will discover how to modify them; how to replace, add or delete elements in processed documents.
JQ and OpenAPI Series - Part 4
Bonus: Coloring JQ's raw output
By Arnaud Lauret, July 6, 2020
Ever wanted to quickly find, extract or modify data coming from some JSON documents on the command line? JQ is the tool you’re looking for. The three previous parts of this JQ and OpenAPI Series, taught us to extract data from JSON (OpenAPI) files and modify them using many filters, creating modules and using command line arguments. To finish this series, we’ll learn to color JQ’s raw terminal output and do a colored version of part 2’s search operations.
Want to learn how to design simple, user friendly, secure and implementable APIs that do everything they should?
Use code fcclauret to get 37% off my book The Design of Web APIs (works also on any other Manning product!).
Disclosure: the link above is an affiliated link, meaning, at no additional cost to you, I will earn a commission if you click through and make a purchase.