What OpenAPI and Swagger Are

A contract for HTTP APIs

The OpenAPI Specification (OAS) is a standard, language-agnostic format for describing HTTP APIs in YAML or JSON: which endpoints exist, which parameters and request bodies they accept, which responses and status codes they return, the shape of every payload, and how clients authenticate. Because the description is machine-readable, tools can generate interactive documentation, client SDKs, server stubs, mock servers, tests and validation from one source of truth. The format began as the Swagger Specification at Wordnik (2011); in 2015 it was donated to the OpenAPI Initiative under the Linux Foundation and renamed. Swagger 2.0 is therefore OpenAPI 2.0; OpenAPI 3.0 (2017) reorganised the format, and OpenAPI 3.1 (2021) aligned schemas fully with JSON Schema 2020-12. Today "Swagger" usually refers to SmartBear's tools: Swagger UI, Swagger Editor and Swagger Codegen. OpenAPI describes request-response HTTP APIs; event-driven, message-based APIs use the sister specification AsyncAPI.

One description, many outputs

A single OpenAPI document feeds documentation, client code, server stubs, mocks and tests.

A minimal OpenAPI 3.1 document

Enough to describe one endpoint and render documentation.

openapi: 3.1.0
info:
  title: Bookstore API
  version: 1.0.0
  description: Browse and order books.
servers:
  - url: https://api.bookstore.example.com/v1
paths:
  /books/{bookId}:
    get:
      summary: Get a book by id
      operationId: getBook
      parameters:
        - name: bookId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: The book
          content:
            application/json:
              schema:
                type: object
                required: [id, title, priceInr]
                properties:
                  id: { type: string }
                  title: { type: string }
                  priceInr: { type: number }
        '404':
          description: Book not found

OpenAPI is not REST itself

OpenAPI describes any HTTP API, well designed or not. It documents your design decisions; it does not make an API RESTful or consistent by itself. Pair it with an API style guide.

Quick check: What is the relationship between Swagger 2.0 and OpenAPI?

• Swagger 2.0 was renamed OpenAPI 2.0 when donated to the OpenAPI Initiative
• They are unrelated formats
• OpenAPI is a Swagger UI plugin
• Swagger 2.0 is newer than OpenAPI 3.1