OpenAPI 3.1 Specification

OpenAPI (formerly Swagger) is the most widely adopted standard for describing REST APIs. An OpenAPI document (YAML or JSON) formally defines every endpoint, its parameters, request body schemas, response schemas, security requirements, and example values. It serves as a contract between API producer and consumer. OpenAPI 3.1 aligns fully with JSON Schema 2020-12, enabling richer schema features like exclusive minimum/maximum, $vocabulary, and unevaluatedProperties. Tools like Swagger UI, Redoc, and Stoplight render the specification into interactive documentation that lets developers try requests without writing any code.

Example

# openapi.yaml — OpenAPI 3.1 example
openapi: 3.1.0
info:
  title: Products API
  version: 1.0.0
  description: Manage product catalog
  contact:
    name: API Support
    email: api@example.com
  license:
    name: MIT

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: http://localhost:8000/v1
    description: Development

security:
  - bearerAuth: []

paths:
  /products:
    get:
      summary: List products
      operationId: listProducts
      tags: [Products]
      parameters:
        - name: status
          in: query
          schema: { type: string, enum: [active, archived] }
        - name: page
          in: query
          schema: { type: integer, minimum: 1, default: 1 }
        - name: perPage
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
      responses:
        '200':
          description: Paginated product list
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProductList' }
        '401': { $ref: '#/components/responses/Unauthorized' }

components:
  schemas:
    Product:
      type: object
      required: [id, name, price]
      properties:
        id:    { type: integer }
        name:  { type: string, maxLength: 200 }
        price: { type: number, minimum: 0 }
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

HTML

Full Editor

Related Resources

REST API Reference

Complete tag & property list

REST API How-To Guides

Step-by-step practical guides

REST API Exercises

Practice what you've learned