Open in app

Sign in

Write

Sign in

OpenAPI / Swagger Resource List for API Developers

Heitor T. Sergent
Runscope
Published in
8 min readApr 4, 2017

Update 06/06/18: Check out openapi.tools for another great resource on OpenAPI tools.

What is the OpenAPI / Swagger Specification?

The OpenAPI Specification, formerly known as Swagger Specification, is a simple yet powerful way of describing RESTful APIs, in a machine and human readable format, using JSON or YAML. It has a large ecosystem of tools that can help you design, build, document, test, and visualize your APIs.

Here’s what a “Hello, World” example looks like:

The OpenAPI spec seems to be the most popular option among the three major formats the community is currently using for describing APIs (RAML and API Blueprint being the two others). It is used by companies of all sizes, including Microsoft, Netflix, IBM, and Lyft, to name a few.

The three major benefits of creating and using an OpenAPI specification are:

  • Generating interactive documentation — API documentation is often overlooked, but it’s crucial for developers to understand how to interact with your endpoints, whether they’re internal or external code.
  • Human readable and machine readable — The choice of JSON and YAML as the accepted formats is not by accident. Being language-agnostic is an important aspect of the OpenAPI specification widespread use, allowing teams to easily read and share them, while making it easy to create tooling around it for any programming language.
  • Creating SDK for multiple languages — A big challenge that API companies face is providing client libraries for multiple languages and frameworks: Node.js, C#, Python, Ruby, Java, etc., the list could go on forever. OpenAPI tooling such as swagger-codegen can help you do that with little work.

Another benefit of the OpenAPI specification is that it does not require you to rewrite your existing API. You can even find unofficial specs for public APIs. However, OpenAPI is not a one-size-fits-all solution. Not all services can be described by the OpenAPI specification, and it was not intended to cover every possible case of RESTful APIs.

Why the two different names?

The Swagger specification development started in 2010, by Wordnik. It was later acquired by SmartBear, in 2015. In that same year, SmartBear created the OpenAPI Initiative (OAI) under the Linux Foundation, and donated the Swagger specification to it, in order to advance a common standard across industries. A number of tech companies, including Google, IBM, and Microsoft, signed on as founding members of the OpenAPI Initiative, and the Swagger Specification was rebranded as the Open API Specification.

Why are we writing this?

Crafting good APIs is no easy task. OpenAPI brings a lot of benefits to this process, whether you approach it from a design-first or code-first perspective. The ecosystem of tools can help you generate interactive documentation, SDKs for your APIs in multiple languages, and server stubs.

But getting started with OpenAPI can be challenging. Figuring out how to start writing a spec from the ground up or for existing APIs, which tools, cloud providers, and frameworks support the specification, the differences between 1.2, 2.0, and the upcoming 3.0 versions, and finding open-source generators for your SDKs are only a few of the questions you can run into.

That’s why we decided to aggregate the best resources in a single place, and hopefully, guide you on this journey in implementing and making the most of your OpenAPI specification.

What is included in here?

We broke down this guide into the following topics:

  • Writing Spec / Design
  • Documentation
  • Generators
  • Servers
  • Clients
  • Testing & Monitoring
  • Gateways / Management
  • Public Specifications

We really hope you find this useful, and please let us know if you think there are any additional resources we can add here.

Writing Spec / Design

With existing API projects, you can leverage generators to automatically create an OpenAPI specification and documentation for your project. Several of these projects also support code annotations so you can incorporate those in your docs, and you can find generators for the most popular languages and frameworks: Node.js, Python, C#, Go, etc.

The swagger-codegen project is the official project from the Swagger GitHub organization, and it’s used by several companies. It includes options to generate client libraries, server stubs, and docs. We have included it here, and also in the Servers and Clients sections.

Information and Tutorials

Migration Guides

Upcoming 3.0 Specification

Tools

Documentation

One of the most popular benefits of creating an OpenAPI specification is using it to create an interactive documentation, allowing developers to quickly test your API directly from your docs. There are several tools to choose from here, including the open-source Swagger-UI, to ReadMe.io’s more extensive platform.

Information and Tutorials

Public API Examples

Tools

Generators

With existing API projects, you can leverage generators to automatically create an OpenAPI specification and documentation for your project. Several of these projects also support code annotations so you can incorporate those in your docs, and you can find generators for the most popular languages and frameworks: Node.js, Python, C#, Go, etc.

The swagger-codegen project is the official project from the Swagger GitHub organization, and it’s used by several companies. It includes options to generate client libraries, server stubs, and docs. We have included it here, and also in the Servers and Clients sections.

Information and Tutorials

GitHub

Servers

The following tools can help you design and build OpenAPI-compliant APIs, while using your specification to handle parts of the plumbing, such as schema validation, input validation, and routing logic.

Information and Tutorials

Tools

GitHub

Clients

Providing client libraries for multiple languages can be a time-consuming commitment for API providers. Luckily, these tools can help you generate libraries automatically from an OpenAPI specification.

This may not be a panacea for all your SDK woes, but it can give you a good starting point on which you can improve with the help of your API developers and users.

Information and Tutorials

Tools

GitHub

Testing & Monitoring

Some of the open-source projects in the previous sections will help you run unit tests against your API just with your OpenAPI specification.

These projects and tools can help you get a more comprehensive look into your OpenAPI-backed APIs, by running tests against a backend implementation of the API, and providing more information such as performance, response validation, and uptime.

Information and Tutorials

GitHub

Tools

Gateway / Management

API Gateways can help you create, publish, and implement multiple features such as rate limiting, authentication, policies and tiers, just to name a few.

Some of these tools support importing an OpenAPI definition to give you a head-start when deploying a new API, and/or exporting a specification so you can use it for docs or client generation.

Information and Tutorials

Tools

Public Specifications

Looking at how other companies have written their OpenAPI specifications can be helpful when writing your own. Here’s a list of a few specifications available on GitHub:

You can also find a list of official and unofficial API specifications on APIs.guru OpenAPI directory. Check the value of the `x-unofficialSpec` parameter to differentiate between them:

And “The API Stack” project by the API Evangelist is another great resource as well:

Special thanks to some awesome folks:

We hope this resource list helps you make the most out of your OpenAPI / Swagger specification. If you have any feedback or links to other projects, tools, and tutorials we could include here, please reach out to us!

Everything is going to be 200 OK®

Originally published at blog.runscope.com.

API
Swagger
Openapi
Api Development
Api Design

--

--

Heitor T. Sergent
Runscope

Written by Heitor T. Sergent

925 Followers
Editor for

Community Content Lead @Runscope, Founder of devbeers, former developer evangelist at SendGrid & Azuki, love burgers/coffee/hackathon!

Help

Status

About

Careers

Press

Blog

Privacy

Terms

Text to speech

Teams