Supporting The OpenAPI Specification (fka. Swagger Specification) format when creating Web API tools is a must-have. Not for the sake of the format itself but rather because of the benefits you’ll get from it. But those benefits will come only if OpenAPI is used the right way.

OpenAPI, or the OpenAPI Specification, formerly known as the Swagger Specification, is a machine-readable and human-friendly API description format. That short description is correct but does not help to understand what it is OpenAPI: it’s the Rosetta Stone of the Web API world. Let’s see why.

While quickly doing a first scan of latest Postman State of the API Report , I did my Spock face, raising an eyebrow. Indeed, I read that after JSON Schema, “The next most popular specifications were Swagger 2.0 (54%) and OpenAPI 3.0 (40%)”. To be honest and based on my own experience, it’s not totally surprising, I’m still hearing/reading “can you check that Swagger” everyday. But why the 4 years old OpenAPI 3 is still struggling to surpass the good old Swagger 2?

After my first recorded live demo session, here comes my first non recorded actually live session in which I show how I take advantage of the OpenAPI Specification during API design reviews. Note that I experienced some technical issues during this session, you’ll find the story in my “Barely surviving my first live (non recorded) demo session” post.

If you want to discover the OpenAPI Specification format, this video is for you! In my first ever (recorded) live coding session, given at the 2021 Manning API Conference, I demonstrate basic, advanced, and even hidden features that will help you to efficiently create complete, accurate, and maintainable API descriptions when designing documenting APIs.

When working with OpenAPI Specification documents to design and document APIs, there are two approaches: either you write it (directly using a text editor or indirectly using an API design GUI), either you generate it from the implementation’s code (using annotations). Generating OpenAPI Specification documents from code has major drawbacks that you should be aware of in order to choose this approach knowingly.

Thoughtworks Technology Radar 24, an “opinionated guide to technology frontiers”, came out last 15th of April, 2021 and I thought it could be interesting to read it from an API perspective, hence this post sharing my thoughts on it. As always it is really interesting and full of valuable insights, though I nearly fell off my chair while reading the Tools section which talks about OpenAPI linters (if it’s not a click bait, I don’t know what it is).

API Design Reviews can be a total nightmare when it comes to check API Design Guidelines conformance. Hopefully, this can be automated using the OpenAPI Specification and Spectral, helping you to focus on real API design matters.

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.

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.

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.

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.

So you want to explore in depth the OpenAPI Specification version 3.0? You should take the OpenAPI Map with you!

The OpenAPI Visual Documentation has been updated. The new version 3.0.0-rc0 of the OpenAPI specification has been added. The addition brings a fully detailed change log of what has change from version 2.

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.

OpenAPI offers many possibilities that span the full API lifecycle, yet it is seen purely as a solution for generating API documentation. This session will tell the story of AXA Banque's evolution from .doc and .pdf API documentation to the extensive use of OpenAPI Specification (formerly Swagger). Throughout the journey, we will identify the many advantages of API definition languages beyond simply generating API documentation, including design, testing, documentation continuous delivery, code generation, mocking, and prototyping new ideas.

Just before the Developing an API Strategy for 2017 panel, I have been interviewed about Swagger/OpenAPI specification and the API Stylebook by Keshav Vasudevan from Smartbear.

Often reduced to Swagger UI and seen purely as a solution for generating API documentation, the OpenAPI (fka. Swagger) Specification format offers many possibilities that span the full API lifecycle. In this session we will identify some of the many advantages of this API definition from design to production, including topics such as design, mock, development, test, documentation continuous delivery, securely evolve an existing API. All this contributing in accelerating and securing API's lifecycle.

For many still known as Swagger, the OpenAPI specification is often reduce to auto-generated API documentation. But the OpenAPI specification universe is boundless. Design, mock, development, test, documentation continuous delivery, governance, deployment... there are countless possibilities that span the full API lifecycle. Let's board the starship OpenAPI to explore unexpected use cases, to seek out new usage and new ideas, to boldly go where almost no one has gone before.

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.

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.

After mastering input and output modeling like a Jedi, let’s see how we can describe API’s security with the OpenAPI specification’s.

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.

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.

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.

After discovering what is the OpenAPI Specification format, it’s now time to write a first simple OpenAPI Specification file to learn the basics.

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.

When watching a movie, have you ever noticed how characters interact with computers? If someone wants to destroy a computer, what does he or she smash?
The computer’s screen…