What is OpenAPI? Introduction to OpenAPI Specification (OAS)

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.

The OpenAPI Specification does not mandate a specific development process such as design-first or code-first. 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:

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Swagger Petstore
  license:
    name: MIT
servers:
  - url: http://petstore.swagger.io/v1

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.

paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      tags:
        - pets
      parameters:
        - name: limit
          in: query
          description: How many items to return at one time (max 100)
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: A paged array of pets
          headers:
            x-next:
              description: A link to the next page of responses
              schema:
                type: string
          content:
            application/json:    
              schema:
                $ref: "#/components/schemas/Pets"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

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.

components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string
    Pets:
      type: array
      items:
        $ref: "#/components/schemas/Pet"
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string

OpenAPI v3.1 updates

OpenAPI continues to mature. OpenAPI 2.0 was released in 2014, and a major update to OpenAPI 3.0 was made in 2017. In 2021, the OpenAPI Initiative debuted v3.1, which brought some additional interesting improvements to the specification.

One simple, yet important update is inclusion of a summary field within info. For example:

openapi: 3.1.0
info:
	title: Apitracker example API
	version: 1.0.0
	summary: This API displays information about the Apitracker ecosystem
	license:
		name: Apache
		identifier: Apache-2.0
...

One of the bigger changes includes support for webhooks. Callbacks have been supported since OpenAPI 3.0, but now, v3.1 provides a more standard way to define webhooks. You can now specify webhooks in OpenAPI definitions by pointing to a pathItems, which can be defined as a component below. For example, it may look something like this:

webhooks:
	newThingAlert: 
		$ref: '#/components/pathItems/newThingAlert'
components:
	pathItems:
		newThingAlert: Notification that an event has occurred
		post:
			requestBody:
				content:
...

APIs can be represented differently too, since as of v3.1, OpenAPI now supports defining only paths, webhooks, or components, or any combination of the three.

Another major update is support for JSON Schema. "One of the biggest changes in 3.1 is the relationship between OpenAPI and JSON Schema," said Darrel Miller, of the OAI Technical Steering Committee Member. Instead of using a shaky subset of JSON Schema, OpenAPI 3.1 is now more trusting of JSON Schema itself. According to Miller, this makes it easier for the tooling community. "You don't have to write your own OAS-flavored JSON Schema tools. You can just take a dependency on existing ones out there," he said.

For a complete list of updates in OpenAPI v3.1.0, view the announcement here.

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, Postman, 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 Portman, Citrus, Postwoman, Everest, Postman, 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.

Examples of OpenAPI implementations in production

Here are several examples of OpenAPI usage within production settings:

1. Discourse generates API docs using ReDoc

Discourse is one of many companies using ReDoc to auto-generate their public API documentation from an OpenAPI definition. With a three-column layout, ReDoc makes it easy to explore methods, read implementation instructions, and view sample requests and responses. You can view the live Discourse documentation here.

2. SDK auto-generation at Xero

Impressively, Xero, a large account software company, now auto-generates SDKs from its OpenAPI files. Xero developers run YAML OpenAPI files through OpenAPI Generator, a community-driven fork of SwaggerCodeGen. OpenAPI Generator has been used by other groups, such as Square, to quickly generate SDKs with functional documentation.

3. Axlerant uses OpenAPI for definition-driven development

OpenAPI is in use by many development groups to assist design-first development approaches. For example, Axlerant adopts OpenAPI intimately within their development workflow. This has helped the team collaborate on responses and endpoints during the design process, as well as document and version the software appropriately.

4. Postman and OpenAPI

Postman, the highly popular API testing utility, allows developers to easily explore and validate OpenAPI definitions. With OpenAPI support, Postman enables validating and syncing during development, validating API responses, and helps developers better organize their Postman Collections by utilizing OpenAPI tags.

5. How we are using OpenAPI at Apideck

At Apideck, we're using OpenAPI to power our documentation, generate SDKs and enable a transparent process. A transparent, specification-driven API design process helps keep all development in sync and aids our overall API governance. Since launch, we have utilized OpenAPI Specification, and we intend to receive design feedback on the repository itself — this will enable third-party developers to help drive the future of our Unified APIs.

OpenAPI benefits

As you can see, there are many use cases for OpenAPI. But merely demonstrating its use in popular tools doesn't justify adoption. So, what are some end benefits of using OpenAPI?

Well, first off, OpenAPI can streamline internal API development considerately. Coalescing around a common specification helps direct collaborative definition-driven API development, translating into more efficient projects and more targeted rollouts. By conforming to OpenAPI, organizations can also reproduce consistent API style, thus increasing the reusability of internal offerings and powering new innovations in a standardized way.

Next, consider the impact on developer experience. With beautiful documentation, developers can easily explore an API, thus improving the learning process while reducing the effort to upkeep a developer portal. Utilizing OpenAPI tooling to produce additional resources, such as code samples, SDKs, and libraries, can tremendously improve the developer experience while allowing you to cast a wider net to support more programming languages.

Lastly, adopting OpenAPI means supporting the overall API ecosystem. OpenAPI is very-well maintained and adopted — no other API specification has reached its level of standardization. It's a Linux Foundation project with top tech company backing and a bright future. This translates into stability for the spec and stability for the surrounding adopters and integrators.

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.