Table of Contents

[[toc]]

Overview

What is OpenAPI?

When people use the term OpenAPI, in most cases they're probably referring to a REST API specification (schema) written in JSON or YAML based on the OpenAPI Specification (hereafter OAS).

OAS is a standard for describing REST API specifications, and by itself it doesn't provide any tool or service. That said, related tools and services have become widespread, so there's probably no need to be too particular about the exact meaning of the term.

• OpenAPI Specification (v3.0.3)
• Implementer's Draft (OAS 3.1 RC1) Available for Feedback – Please Respond by Nov 8!

The current latest version is 3.0.3, and the next version, 3.1.0, seems to be coming out soon.

OAS is standardized under the leadership of the OpenAPI Initiative.

The OpenAPI Initiative (OAI) was created by a consortium of forward-looking industry experts who recognize the immense value of standardizing on how APIs are described. As an open governance structure under the Linux Foundation, the OAI is focused on creating, evolving and promoting a vendor neutral description format. The OpenAPI Specification was originally based on the Swagger Specification, donated by SmartBear Software. https://www.openapis.org/about

Relationship with Swagger

The keyword Swagger is often used in the same context as OpenAPI, but it isn't something completely unrelated.

For one thing, what used to be known as the Swagger Specification was renamed the OpenAPI Specification. Generally, when you see something described as a "Swagger schema," you can read that as an OAS v2.0 schema. (I haven't used v1.2 and rarely see it mentioned, so I'll leave it out.)

There are some spec differences between v2 and v3, such as structural changes, and some libraries and tools don't support v3 yet, so the situation varies a bit — choose whichever fits your needs. There are tools that convert between v2 and v3, so switching later isn't too difficult either. If there are no particular constraints, I think it's fine to just go with v3.

This repository also contains the OpenAPI Specification 2.0, which is identical to the Swagger 2.0 specification before it was renamed to "OpenAPI Specification", as well as the Swagger 1.2 and Swagger 2.0 specifications. https://github.com/OAI/OpenAPI-Specification#previous-versions

Also, looking at their website, Swagger itself is described as "a set of open-source tools to help you work with the OpenAPI Specification." If you've ever written an OpenAPI schema, you've probably seen Swagger UI at least once.

Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document and consume REST APIs. https://swagger.io/docs/specification/about/

In most cases this too seems to be used to mean roughly Swagger = Swagger (OAS v2.0) schema.

OAS-related tools and services

As mentioned above, OAS is a standard, and I don't think there is an "official" tool or service for it. Swagger might be a borderline case given its history, but I consider it to provide OAS-compliant tooling.

Incidentally, the OAS repository has an Implementations page, though it's unclear whether it's being actively updated. There may be some listing criteria, but it's probably safe to assume what's there is only a partial list. It's also noted that being listed there doesn't imply endorsement of any particular tool.

There are also pages that round up OAS-related tools, such as the following.

• OpenAPI.Tools
• APIs.guru Awesome-OpenAPI3

I can't cover every tool out there, so I'll focus on introducing, as much as possible, the ones I've actually used or ones that have caught my interest.

Swagger

Whatever else you find, when researching OAS you won't avoid running into Swagger.

• https://swagger.io/

Open-source tools

Swagger provides the following open-source tools.

• Swagger Editor
• Swagger UI
• Swagger Codegen

Swagger Editor is a browser-based editor that lets you preview an OAS schema as you edit it, and it also validates the schema, so it's handy for catching mistakes right away. You can try it out on the demo site.

Swagger UI renders an OAS schema in a human-readable UI. (The preview in Swagger Editor is the same thing.) Asking someone to read a schema written in JSON or YAML isn't practical, so this is handy for reviews and for maintaining documentation.

Swagger Codegen can generate server stubs and API clients based on OAS. I'll cover this in more detail together with OpenAPI Generator, discussed later.

These tools are also easy to use via Docker.

• Docker Hub: swaggerapi

SwaggerHub

Swagger provides a SaaS called SwaggerHub, positioned as a platform for teams to collaborate on API design. Put simply, it's something like a hosted version of Swagger Editor and Swagger UI.

With SwaggerHub, teams can easily edit and share schemas. Swagger Editor and Swagger UI are handy, but as team size or the number of projects grows, the operational overhead increases — if that's a concern for you, SwaggerHub might be worth considering.

The Free plan only lets you create public projects, which should be plenty if you're publishing an external-facing API spec. To create private projects — for internal API specs, for example — you'll need a paid plan.

Also, any schema deployed on SwaggerHub is automatically assigned a mock server. If backend and frontend development are separated, this is a great feature since you can start frontend development against a mock server as soon as the schema is ready, with no extra steps. That said, the rate limit is "10 requests per minute per API version," which might be too strict for serious use.

• SwaggerHub: API Auto Mocking

Stoplight

Stoplight is a tool I've been seeing mentioned frequently in OAS-related articles recently, and it seems to have a pretty good reputation. Its position is roughly the same as Swagger's — it provides OAS-related tools as open source while also offering various SaaS features.

• https://stoplight.io/

Studio

Studio is an editor for OAS schemas.

Compared to Swagger Editor, I think the big advantage is that it's editable via GUI. Swagger Editor is fundamentally just an aid for writing JSON or YAML — it offers autocomplete and such, but it basically assumes you already know the syntax. Since Studio can be edited via GUI, you can edit a schema with just basic knowledge of API design, even without knowing the finer details of OAS syntax. (That doesn't mean you no longer need to understand OAS at all, though.)

Another major advantage: as the number of endpoints grows and the JSON or YAML file gets longer, partial edits become tedious — but with Studio's GUI, you can just click to add a path or parameter wherever needed, which makes editing much easier.

If you want to make YAML diffs easier to read as code, I'd also recommend this article.

• How to split and structure an OpenAPI schema

In Studio, you can start a mock server with a single button click. The mock server appears to use Prism, described below, but it looks like Studio doesn't let you change Prism's options such as the port number, so if you want to change those options you'll need to use Prism directly.

• Stoplight Studio: Mock Servers

Prism

Prism is a tool that runs a mock server based on an OAS schema. If you're using Studio and don't need to change any options, you probably don't need to use it directly, but if you're not assuming Studio as a prerequisite, using Prism directly is a good option too.

I've written about trying out Prism in the following article, so please take a look.

• Setting up a mock server with OpenAPI × Stoplight Prism

Spectral

Spectral is a linter for OAS schemas.

There are other tools that check OAS schemas — I had been using the validate command in OpenAPI Generator, described later — but I switched to Spectral because it lets you customize rules and has a VS Code extension available.

One especially nice point about the VS Code extension is that it works fine even with schemas that use $ref file references, as I've introduced in a past article.

• https://github.com/stoplightio/vscode-spectral

Stoplight Platform

Stoplight Platform is a service similar to SwaggerHub for Swagger.

With Stoplight Platform, teams can edit schemas together and manage documentation. The documentation format looks similar to Swagger UI, but you also seem to be able to write Markdown separately from the OAS schema. It also seems that even the Free plan allows you to create private projects.

A CLI is also provided, so it seems possible to have CI update information for a specific repository or branch.

It gives quite a similar impression to SwaggerHub, but since you can create private projects for free, this might be the better option if you just want to try running some project with it first.

OpenAPI Generator

OpenAPI Generator can generate server stubs and API clients based on OAS.

• https://github.com/OpenAPITools/openapi-generator

Just looking at this, you might think it's the same as Swagger Codegen — so what's the difference, and which should you choose? According to the following article, this was originally forked by some of the members who developed Swagger Codegen, and it's now developed in a community-driven way. So while Swagger Codegen and OpenAPI Generator fall into the same category of tool, their development status and policies differ, so which to choose is really up to the user.

• Akatsuki: OpenAPI Generator — A code generator that grows through community-driven development

I haven't touched much on the part where you generate and use API client code myself, but it seems like a common opinion that OpenAPI Generator supports more languages and is developed more actively. The following article compares the languages supported by Swagger Codegen and OpenAPI Generator, so if both support your language, it might be worth comparing the generated code before deciding. I had been using them without thinking much about the differences, so this was a good opportunity to reconsider.

• Rhyztech blog: Comparison of Swagger Codegen and OpenAPI Generator (Feb 2020 edition)

I also use it to merge split YAML schemas into a single JSON schema, and to generate Markdown documentation.

For client-side usage, please also see the following article.

• A rich, type-safe client life made possible by auto-generation with OpenAPI Generator + TypeScript

Server stubs

I haven't made much use of server stubs myself, but generating them is just as easy as generating API clients. I had assumed the term server stub carried a similar nuance to a mock server — something to replace the API server during testing — but Swagger's documentation says it's also fine to use it as a base for implementing logic and deploying. (I'm using "server stub" as the base term here, though "スタブサーバー" seems to be the more common way to phrase it in Japanese.)

With SwaggerHub, you can easily generate a server stub (an API implementation stub) for Node.js, ASP.NET, JAX-RS, and other servers and frameworks. The server stub is a good starting point for implementing your API – you can run and test it locally, implement the business logic for your API, and then deploy it to your server. https://app.swaggerhub.com/help/apis/generating-code/server-stub

Even without implementing the logic, if a mock like Prism, mentioned above, can't give you fine-grained control over the response content, a server stub might help by letting you control the response data in detail to suit your needs.

Using a server stub takes a bit more effort than a mock server, but it seems worth choosing depending on the situation. There are various kinds of server stubs too — for JavaScript, nodejs-express-server is available, for example.

Using OAS on the server side

The tools introduced so far were mainly aimed at OAS design and supporting client-side development.

So how can the server side, which actually implements the API, make use of it? Even if frontend implementation proceeds according to an OAS schema, it's meaningless if the data the backend's implemented API actually returns doesn't match. To avoid that kind of problem, the server side should also implement its API in accordance with the OAS schema, and ideally there should be a mechanism that guarantees this.

There are countless approaches to schema-driven development, so I can't cover them all, but I'll introduce our company's approach as one example.

Ruby on Rails

At our company, Ruby on Rails (hereafter Rails) is one of our main choices for implementing API servers.

There are libraries that generate Ruby code from an OAS schema, or that let you write OAS definitions inside Rails code and generate a schema from them, but we're not using them currently because their support for newer OAS versions varies, and some introduce dependencies on other libraries. Basically, we just write an OAS schema and implement code that follows it.

I've written an article about using committee-rails to verify whether Rails is returning responses that follow the OAS schema, so please take a look.

• Schema-first API development with committee × OpenAPI × Rails

While I can't say this is a perfect solution as it stands, we're currently able to verify through tests that API responses follow the OAS schema, so we consider it good enough for now.

Laravel (PHP)

Besides Rails, we also do API development with Laravel, and we run similar tests using the following library.

• https://github.com/thephpleague/openapi-psr7-validator

Alternatives to OAS

When designing a REST API, OAS isn't the only option — RAML and API Blueprint are commonly seen as points of comparison. There are also tools that convert between them, so it might be interesting to compare how a schema written in OAS would look elsewhere.

RAML

RAML stands for RESTful API Modeling Language, and as the name suggests, it's a language for designing REST APIs. RAML definitions, written in YAML, give an impression that's fairly close to OAS at first glance.

• https://raml.org/

It supports API design, generating and sharing documentation, and even automatic code generation, so its ecosystem seemed fairly close to OAS as well.

Incidentally, MuleSoft, a central figure in RAML's development, is a participant in the OpenAPI Initiative, and their view seems to be that RAML doesn't compete with OAS but coexists within the same ecosystem.

• https://blogs.mulesoft.com/dev/api-dev/open-api-raml-better-together/

There are certainly adoption cases, but compared to OAS, I felt its presence was a bit thinner.

API Blueprint

API Blueprint is an API specification language developed as open source by Apiary.

• https://apiblueprint.org/

Compared to OAS and RAML, API Blueprint is distinctive in that it's written in Markdown. It might just be a matter of familiarity, but personally I found writing OAS in YAML to be the easiest.

A lot of surrounding tooling is provided too, so it seems fully capable for API design, documentation, and introducing it into development. However, there don't seem to be many tools or services that can import API Blueprint definition files, so it might be a viable option if you're prepared to cover everything using Apiary and API Blueprint together.

Incidentally, Apiary's SaaS supports not just API Blueprint but also editing OAS definition files and hosting them as documentation. The UI shows "Swagger," but it also supports OAS v3.0, and while it differs from Swagger UI, it does support previews and requests to a mock server.

• Welcoming OpenAPI 3.0 to Apiary

Summary

I've given an overview of OAS and introduced just a small slice of the tools around it. I plan to keep updating and adding to this whenever something comes to mind. Personally, I think Stoplight's tools look promising, so I'd like to keep following how they develop.

OAS isn't just about describing and documenting a REST API spec — being able to use the tooling that grows out of its ecosystem is a big part of its appeal. Of course, from a schema-first perspective there are other options too, like GraphQL, so it's worth comparing alternatives rather than sticking rigidly to OAS.

If you already have existing REST API code, rather than just writing documentation purely for show, defining an OAS schema could let you introduce things like documentation generation and REST API testing incrementally.

Having a lot of adoption cases is certainly a strong push toward adopting something, but now that I've been working with OAS for a while, I found myself wanting to take another look at RAML and API Blueprint as well.