What is OpenAPI?

OpenAPI Specification (OAS) has become the standard way to define HTTP APIs. Like a universal adapter, an OpenAPI definition describes API methods and metadata, increasing API knowledge and portability across environments. Commonly used in auto-documentation, code generation, and design-first development, OpenAPI's pivotal role across many areas of the API economy cannot be overstated.

The offspring of Swagger, OpenAPI is now a vendor-neutral standard supported by the OpenAPI Initiative, a Linux Foundation project. With this strong backing, OpenAPI continues to evolve and sustain a vibrant, interconnected API economy. Below, we'll define what exactly OpenAPI is, how OpenAPI definitions are structured, and peek into some production implementations that demonstrate the power of OpenAPI.

What is OpenAPI?

OpenAPI is a standard way to describe HTTP-based APIs. Formerly known as Swagger, Smartbear donated OpenAPI in 2015 with the formation of the OpenAPI Initiative (OAI), an industry consortium governed by about 40 participating members representing some major tech interests.

So, what does OpenAPI accomplish? Well, think of OpenAPI as a lingua franca for everything API. Building off a common spec enables collaborative, design-first development practices. If you are iteratively improving your APIs, utilizing an API schema as a source of truth is vital to conform to API style and governance policies. With this source of truth, engineers can also auto-generate valuable materials, such as documentation, SDKs, code libraries, and more, thus reducing development effort. In fact, many tools exist to help developers leverage the power of OpenAPI to enable conversion, validation, linting, and other capabilities.

To understand OpenAPI, it helps to clarify three terminologies that are often conflated — specification, definition, and documentation:

• OpenAPI Specification (OAS): The industry-standard specification that outlines how OpenAPI files are structured, outlined here.
• OpenAPI Definition: Your actual API definition file that represents your specific API use case. This schema is machine-readable and represented in either YAML or JSON.
• API Documentation: The visual, human-readable representation of the API structure. Applies HTML, CSS, and JavaScript to enable API navigation and discovery.

In short, OpenAPI makes APIs more shareable, extensible, reusable, and consistent for both internal and external stakeholders. So, what does it look like?

OpenAPI definition structure

Let's explore a sample OpenAPI definition. Below, we'll reference the petstore.yaml, a v3.0 OpenAPI file located here. Visually, a basic OpenAPI definition is structured as follows:

The info field contains high-level information about the API, such as version, title, and license. The server field denotes the root endpoint for the API. For example:

Next, an OpenAPI file outlines the paths for the API. These describe the specific methods that can be reached, as well as their parameters, responses, human-readable descriptions of functionality, accepted content types, tags, and other expected behaviors. For example, here is a get call to the /pet path.

An OpenAPI definition would likely define many more paths, as well as additional HTTP method operations for the same path, such as post, put, or delete.

Another useful object is the components object, which holds a set of reusable objects for different OAS elements to reference throughout the spec.

Helpful OpenAPI tools

A clear benefit to adopting OpenAPI is leveraging the expansive tooling ecosystem around it. Many open-source and vendor tools help API developers develop, test, document, and generate support code around their API. Kin Lane has done a great job of organizing some of these most useful tools within the API Specification Toolbox repository, also viewable on this website. OpenAPI.tools is another comprehensive resource. Below, we've summarized some of the most popular OpenAPI tools throughout a few key areas.

• ?? Editors: API design editors utilize OpenAPI to guide design-first API development. Examples include SwaggerHub, Visual Studio Code extension, KaiZen OpenAPI Editor, Stoplight, Insomnia Designer, Optic, and Curio.
• ?? Documentation: Many free tools auto-generate documentation and visualizations to aid API onboarding and navigation. Some examples are ReDoc, Swagger UI, Widdershins, and openapi-viewer.
• ?? Code Generation: Some packages can generate SDKs and helper libraries from an OpenAPI definition. Examples include OpenAPI-generator, Google Gnostic, Gen, and swagger-node-codegen.
• ?? Testing: Testing and mocking tools are critical to helping verify functionality and spotting security issues. Examples include Postman, Citrus, Postwoman, Everest, and APIFortress.
• ?? Server Implementations: Certain tools like FastAPI and openapi-backend help support the server backend for an OpenAPI-compliant web API.
• ?? Discovery: Some API directories and search engines require OpenAPI files to be profiled. Examples include APIs.guru, the public-apis list on Github, and API Tracker. As we've previously covered, listing your API within these directories is an excellent way to promote your API.
• ?? Validation: Tools such as OpenAPILint and Spectral by Stoplight help lint your definition and validate it against OAS norms.
• ?? Format Conversion: API Transformer from APImatic aids transformation between API specifications. A similar tool is Odata-openapi.
• ?? API Management: API management is a somewhat nebulous term but typically involves hosting, securing, and monetizing the API as a service. OpenAPI is quite popular among API management offerings. Some open-source options include API Umbrella and APIman..

Conclusion: API owners — you probably need an OpenAPI definition

For years, the API industry searched for a specification to represent commonalities among thousands of APIs. Today, OpenAPI indeed dominates the market — however, to be fair, it's one of many API specification options. AsyncAPI, JSON Schema, RAML, GraphQL, and SOAP provide other ways to describe and document APIs. "All of these API specifications are continuing to see massive adoption across API providers and consumers," wrote Kin Lane.

Nevertheless, OpenAPI has found an intrinsic home within the majority of modern API developer toolkits. By standardizing how HTTP APIs are defined, OpenAPI enhances internal reusability and external consumption. With backing from tech giants like Google, IBM, eBay, Microsoft, and Mulesoft, it seems OpenAPI is here to stay. For all the benefits outlined above, if you don't already have an OpenAPI definition for your API program, it may be a good idea to consider it.

Originally posted at https://blog.apideck.com/introduction-to-openapi-specification