OpenAPI and Swagger for API Documentation

You should definitely take a closer look at Swagger, because as an application developer you’ll inevitably work with APIs at some point. Swagger becomes your best friend once you know how to use it. It’s not difficult either, and even if you need an API key beforehand, that’s still manageable. Like Postman, Swagger gives you a ready-made test interface. You select the endpoint and can start a test request immediately.

OpenAPI is the standard for machine-readable descriptions of REST APIs and forms the foundation for interactive documentation, mock servers, and code generation.

Quick Overview

OpenAPI is a specification format for REST APIs that describes endpoints, methods, parameters, request and response schemas, status codes, error formats, and security mechanisms. It’s typically written in YAML or JSON and serves as a single source of truth for developers, testers, client generators, and documentation tools. Swagger is a brand name used today for a suite of tools around OpenAPI, including Swagger UI, Swagger Editor, and Swagger Codegen. OpenAPI enables API-first design, automated testing, and the creation of interactive API documentation. A good OpenAPI specification is complete, consistent, and enriched with examples so users can understand and try out the API without reading the code.

Key Components

OpenAPI Version

OpenAPI is available in versions 2.0, 3.0, and 3.1. Versions 3.0 and 3.1 offer more flexibility than 2.0, particularly for request and response definitions, links, and callbacks. For new projects, use a current version and maintain older versions only for compatibility reasons.

Info and Metadata

The info block contains basic information such as title, version, description, and contact details. These metadata are essential for identifying the API and enabling automated documentation.

Server URLs

Server URLs define the addresses where the API is accessible. You can specify multiple environments like development, staging, and production. Variables allow you to make parts of the URL dynamic.

Paths and Operations

Paths describe the API’s endpoints. Each path can contain multiple operations such as get, post, put, delete, or patch. Each operation includes a summary, description, tags, parameters, request body, and responses.

Components and Schemas

Components contain reusable definitions like schemas, parameters, responses, headers, and security schemas. Schemas define the data structure of requests and responses with types, required fields, formats, and examples.

Parameters

Parameters can be transmitted in the path, query string, header, or cookie. They’re defined with a name, type, format, required flag, and description. Examples and validation rules like minLength or pattern improve quality.

Request Body

The request body describes the data that the client must send for POST, PUT, or PATCH operations. It typically references a schema and can support multiple content types like application/json or application/xml.

Responses

Responses define the possible answers from an operation. Each status code is documented with a description, content type, and schema. Error responses like 400 or 404 should be fully documented as well.

Security Schemas

Security schemas describe how the API is secured. Common approaches are HTTP Basic, Bearer Token, OAuth2, and API Keys. The schemas are defined in Components and referenced in operations.

Swagger UI and Redoc

Swagger UI and Redoc are tools that generate interactive HTML documentation from an OpenAPI specification. Swagger UI lets you try endpoints directly in the browser, while Redoc emphasizes attractive presentation and readability.

Code Generation

OpenAPI Generator produces client and server code from the specification. This speeds up development, reduces errors, and ensures client and server are based on the same contract. Many programming languages and frameworks are supported.

Practical Example

A shop defines its order API with OpenAPI:

openapi: 3.0.3
info:
  title: Shop API
  version: 1.0.0
  description: API für die Verwaltung von Bestellungen

servers:
  - url: https://api.shop.example.com/v1

paths:
  /orders:
    post:
      summary: Bestellung anlegen
      tags:
        - Orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderRequest'
      responses:
        '201':
          description: Bestellung erstellt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: Ungültige Eingabe

components:
  schemas:
    OrderRequest:
      type: object
      required:
        - customerId
        - items
      properties:
        customerId:
          type: integer
          example: 123
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
    OrderItem:
      type: object
      required:
        - productId
        - quantity
      properties:
        productId:
          type: integer
          example: 42
        quantity:
          type: integer
          minimum: 1
          example: 2
    Order:
      type: object
      properties:
        orderId:
          type: integer
          example: 98765
        status:
          type: string
          example: created

From this specification, Swagger UI can generate interactive documentation, OpenAPI Generator can create clients for JavaScript, Python, or Java, and testers can perform schema validation.

FAQ: OpenAPI and Swagger

1. What is OpenAPI?

OpenAPI is a machine-readable format for describing REST APIs. It defines endpoints, methods, parameters, schemas, status codes, and security mechanisms.

2. What is the difference between OpenAPI and Swagger?

OpenAPI is the specification. Swagger is a brand name for tools like Swagger UI, Swagger Editor, and Swagger Codegen that work with OpenAPI documents. The specification itself was formerly called Swagger.

3. What format is OpenAPI written in?

OpenAPI is written in either YAML or JSON. YAML is more commonly used because of its better readability, while JSON is often used for automated processing.

4. What is Swagger UI?

Swagger UI is a tool that generates interactive HTML documentation from an OpenAPI specification. Users can try endpoints directly in the browser.

5. What is Redoc?

Redoc is an open-source tool that generates attractive and readable documentation from OpenAPI specifications. It’s particularly suited for end-user documentation.

6. What are Components in OpenAPI?

Components contain reusable definitions like schemas, parameters, responses, and security schemas. They enable consistent and maintainable specifications.

7. What is code generation with OpenAPI?

Code generation produces client or server code from an OpenAPI specification. It speeds up development and ensures client and server are based on the same contract.

8. What is a schema in OpenAPI?

A schema in OpenAPI defines the structure of data. It specifies types, required fields, formats, examples, and validation rules for request bodies and responses.

9. What are Security Schemas?

Security schemas describe how the API is secured. Common approaches are Bearer Token, API Keys, HTTP Basic, and OAuth2. They’re defined in Components and referenced in operations.

10. What is a Single Source of Truth?

A single source of truth is one authoritative source of information. OpenAPI is the single source of truth for the API, from which documentation, tests, and code are generated.

11. What is API First Design?

API First Design means creating the API specification before implementation. OpenAPI is the central tool for this approach.

12. What is a Mock Server from OpenAPI?

A mock server simulates an API based on an OpenAPI specification. It delivers predefined responses and allows you to develop clients before the actual API is ready.

13. What is the benefit of OpenAPI for testers?

Testers can use OpenAPI to create schema validation, contract tests, and automated tests. The specification serves as a reference for expected requests and responses.

14. What is OpenAPI Linting?

OpenAPI linting checks the specification for rule violations, inconsistencies, and missing components. Tools like Spectral help ensure high-quality specifications.

15. What are best practices for OpenAPI specifications?

Best practices include complete endpoints and responses, reusable components, meaningful examples, clear descriptions, correct security schemas, versioning, and regular maintenance of the specification.

Continue Your API Learning Path

The next article in the API learning path covers API Documentation Best Practices — how to write API documentation that developers can understand and actually use.

References

Recommended Books on API Development

If you’d like to dive deeper into OpenAPI, API documentation, and API design, we recommend these books:

API Development

Books about API design, REST, GraphQL, OpenAPI and API architecture

Designing Data-Intensive Applications von Martin Kleppmann

Bei Amazon ansehen

Affiliate-Link: Bei einem Kauf erhalten wir möglicherweise eine Provision.

API Design Patterns von JJ Geewax