OpenAPI Specification: Documenting Your API the Standard Way

Quick answer: The OpenAPI Specification is a standard, machine readable format for describing REST APIs: their endpoints, parameters, request bodies, responses and authentication. It is the Swagger 2.0 specification under a new name, after SmartBear donated it to the OpenAPI Initiative under the Linux Foundation. You write one file in YAML or JSON, and tools such as Swagger UI, Swagger Editor and Swagger Codegen turn it into interactive documentation, client libraries, server stubs and tests. Writing the spec before the code helps teams agree on the API early and keeps documentation accurate.

Anyone who has integrated with a poorly documented API knows the pain: guessing at field names, discovering error formats by trial and error, emailing the provider for an example. A shared, standard description format fixes much of that. If you build or commission APIs, the OpenAPI Specification is worth understanding.

Swagger, OpenAPI: what changed

Swagger started as an open source project for describing APIs, and grew into the most widely used format of its kind. Late last year SmartBear, which owned the Swagger brand, contributed the specification to a new body, the OpenAPI Initiative, hosted by the Linux Foundation with members including Google, Microsoft, IBM, PayPal and others. In January the specification itself was renamed the OpenAPI Specification.

In practice:

• The specification (the file format) is now called OpenAPI. The current version is 2.0, the same format as Swagger 2.0.
• The tools keep the Swagger name: Swagger UI, Swagger Editor and Swagger Codegen.
• Existing Swagger 2.0 files are valid OpenAPI files. Nothing needs converting.

The move matters because a neutral home makes it more likely that the format becomes a lasting industry standard rather than one vendor’s product.

What a spec file contains

An OpenAPI document describes everything a developer needs to call your API. The main sections are:

• info: the API’s title, version, description and contact details.
• host, basePath and schemes: where the API lives, for example api.example.com, /v1, over https.
• paths: each endpoint and the HTTP methods it supports.
• parameters: path, query, header and body inputs, with types and whether they are required.
• responses: the status codes each operation returns and the shape of the response body.
• definitions: reusable data models, such as a Customer or an Order.
• securityDefinitions: how clients authenticate, such as API keys, basic authentication or OAuth 2.

A short example

Here is part of a spec in YAML for a simple orders API:

swagger: "2.0"
info:
  title: Orders API
  version: "1.0"
host: api.example.com
basePath: /v1
schemes:
  - https
paths:
  /orders/{orderId}:
    get:
      summary: Get a single order
      parameters:
        - name: orderId
          in: path
          required: true
          type: string
      responses:
        200:
          description: The order
          schema:
            $ref: "#/definitions/Order"
        404:
          description: Order not found
definitions:
  Order:
    type: object
    properties:
      id:
        type: string
      status:
        type: string
        enum: [pending, paid, shipped]
      total:
        type: number

Note that the first line still reads swagger: "2.0". That is correct for the current version of the specification.

Why use a standard format

Documentation that stays accurate

Hand written documentation drifts out of date as the API changes. When the spec is the source of truth, and documentation is generated from it, the two stay in step.

Interactive docs for free

Swagger UI reads your spec and produces a browsable page where developers can see every endpoint and try requests directly in the browser. That alone removes a lot of support questions.

Generated client and server code

Swagger Codegen produces client libraries in many languages, and server stubs for several frameworks. Partners integrating with you can start from a generated client rather than writing every request by hand.

Testing and mocking

A spec describes what valid requests and responses look like, which makes it a natural basis for automated tests and for mock servers. Front end developers can build against a mock before the real API is finished.

Better conversations

A spec is something product owners, developers and partners can review together. Disagreements about field names or error handling surface before anyone has written code.

Design first or code first

There are two ways to arrive at a spec.

Design first

Write the spec before building the API. Review it with the people who will use it, generate a mock, and only then implement. This approach tends to produce cleaner, more consistent APIs, because the design is considered as a whole. It suits public and partner APIs, and any project where several teams depend on the interface.

Code first

Build the API, then generate the spec from annotations or comments in the code. Many frameworks have libraries that do this. It is quicker to start and keeps the spec close to the implementation, but the design can end up shaped by the code rather than by the needs of consumers.

Both work. For new APIs that others will rely on, we generally prefer design first. Our guide to REST API design covers the principles that make a spec worth following.

Writing a good spec

• Describe everything. Every parameter, every response code, including errors. A spec that only documents the happy path leaves developers guessing.
• Use definitions for shared models. Define an Order once and reference it everywhere, so changes happen in one place.
• Write human descriptions. Types tell a developer what a field is; descriptions tell them what it means and when to use it.
• Include examples. Example requests and responses are often the first thing developers look at.
• Document errors consistently. Use a standard error format across the API and describe it in the spec.
• Version deliberately. Put the version in the info section and in the base path or headers, and record changes.
• Validate the file. Swagger Editor highlights errors as you type, and command line validators can check specs in your build process.

Tools worth knowing

• Swagger Editor: a browser based editor with live validation and a preview of the documentation.
• Swagger UI: generates interactive documentation from a spec. It can be hosted on your own site.
• Swagger Codegen: generates client libraries, server stubs and documentation in many languages.
• Framework integrations: libraries for most popular frameworks can generate a spec from code or validate requests against one.
• API platforms: several API management products import OpenAPI files to configure gateways and developer portals.

Where OpenAPI fits in a project

When we build a custom API for a client, the spec becomes part of the deliverable alongside the code. It gives partners a clear contract, gives your own developers a reference, and makes future work on the API faster. It also makes API integration projects smoother, because the people connecting to your system have an accurate description from day one.

FAQ

Is OpenAPI the same as Swagger?

The specification formerly called Swagger is now called OpenAPI. The tools still carry the Swagger name.

Do I need to convert my Swagger 2.0 files?

No. Swagger 2.0 files are OpenAPI 2.0 files.

Does OpenAPI work for SOAP or GraphQL APIs?

No. It is designed for REST style HTTP APIs. SOAP services use WSDL, and other API styles have their own approaches.

YAML or JSON?

Either. YAML is easier for people to read and write; JSON is easy for tools to generate. They are interchangeable.

APIs people can actually use

A well described API saves time for every developer who touches it, including your own team. We design, document and build APIs with clear specs from the start. See our custom development services.