Runscope API Monitoring    Learn More →

OpenAPI / Swagger Resource List for API Developers

By Heitor Tashiro Sergent on .

 
The Open API Initiative (also known as OAI) logo
 

Last updated: August 14, 2017

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:

A Swagger YAML example, showing one endpoint /hello that accepts a name parameter

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 3.0.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
  • Other Resources

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

Whether you already have an API or are creating one from scratch, writing your OpenAPI specification is the first step in getting the most out of its ecosystem of tools.

The OpenAPI Specification itself can be found in OAI/OpenAPI-Specification GitHub repository. The latest version released was 3.0.0, and you can find a detailed description of the schema and all its objects here.

Information and Tutorials

Migration Guides

3.0.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



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:


Other Resources

We try to keep this list updated as much as possible, but you can also find more information outside of it. Specific to the 3.0.0 specification, you can find a list of tools that implement and support it in the OpenAPI-Specification repository:

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!


Do you have an OpenAPI definition for an API you'd like to start testing and monitoring? Learn more about Runscope's cloud-based API testing solution and sign up for your free trial account today.


Categories: api ecosystem, openapi, swagger

Everything is going to be 200 OK®