Skip to content

Documenting REST APIs with OpenAPI

OpenAPI

The OpenAPI Specification (OAS) is a standard for describing RESTful APIs. It provides a structured way to define the endpoints, request/response formats, authentication methods, and other aspects of an API in a machine-readable format. The OpenAPI Specification is typically written in YAML or JSON.

An OpenAPI document (often referred to as a "swagger file" in earlier versions) includes details such as:

  • Paths: Endpoints of the API.
  • Operations: Methods (e.g., GET, POST) supported by each endpoint.
  • Parameters: Query parameters, path parameters, etc.
  • Request Bodies: The structure and format of data sent in requests.
  • Responses: Expected responses, including status codes and response bodies.
  • Security: Authentication methods.
Example of a simple OpenAPI document in YAML: 
openapi: 3.0.0
info:
    title: Sample API
    version: 1.0.0
paths:
    /users:
        get:
        summary: List all users
        responses:
            '200':
            description: A JSON array of user names
            content:
                application/json:
                schema:
                    type: array
                    items:
                    type: string

JSON Schema

JSON Schema is a vocabulary that allows you to annotate and validate JSON documents. It is used to define the structure and constraints of JSON data, ensuring that the data adheres to a specified format.

JSON Schema supports the following basic data types:

  • string for character values
  • number for integer and decimal values
  • object for associative arrays (i.e., dictionaries in Python)
  • array for collections of other data types (i.e., lists in Python)
  • boolean for true or false values
  • null for uninitialized data

Example

JSON Schema can be used to describe the properties of JSON objects, including:

  • Types: Define the data types (e.g., string, number, object).
  • Properties: Describe the attributes of an object.
  • Constraints: Specify rules for data (e.g., required fields, value ranges).
Example of a JSON Schema: 
{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "User",
    "type": "object",
    "properties": {
        "name": {
        "type": "string"
        },
        "age": {
        "type": "integer",
        "minimum": 0
        }
    },
    "required": ["name", "age"]
}

Swagger

Swagger originally referred to a set of tools for implementing the OpenAPI Specification. It was created by SmartBear Software and has become one of the most widely used frameworks for API documentation and testing.

Swagger includes:

  • Swagger UI: An interactive documentation tool that automatically generates a user interface based on an OpenAPI document. It allows users to test API endpoints directly from the documentation.
  • Swagger Editor: An online editor for creating and editing OpenAPI documents with real-time preview and validation.
  • Swagger Codegen: A tool for generating client libraries, server stubs, and API documentation from an OpenAPI document.

Swagger tools work with OpenAPI documents to facilitate API design, documentation, and client generation.

Relationship Between OpenAPI, JSON Schema, and Swagger

  • OpenAPI: A specification for describing RESTful APIs. OpenAPI documents can be written in YAML or JSON.
  • JSON Schema: A vocabulary for validating and annotating JSON documents. OpenAPI uses JSON Schema to define the data models for API requests and responses.
  • Swagger: A set of tools for working with OpenAPI documents, including generating interactive documentation, client libraries, and server stubs.

Together, these technologies provide a comprehensive ecosystem for designing, documenting, validating, and interacting with APIs.

Reference