Open API essentials

open-api-example.yaml

# Official reference: https://swagger.io/specification/

openapi: "3.0.0"  # The version of the OpenAPI Specification being used
info:  # Metadata about the API
  version: "1.0.0"  # Version of the API
  title: "Sample API"  # Name of the API

servers:  # Base URL and other server information
  - url: "http://api.example.com/v1"

paths:  # Paths and operations of the API
  /users:
    get:  # An operation
      summary: "List all users"  # A brief summary of the operation
      operationId: "listUsers"  # A unique identifier for the operation
      responses:  # The expected responses
        '200':  # A response
          description: "A list of users."  # A description of the response
          content:  # The content of the response
            application/json:  # The media type of the response content
              schema:  # The schema defining the type used for the response.
                type: "array"  # The type of the items in the array
                items: 
                  $ref: "#/components/schemas/User"  # Reference to a schema definition
    post:
      summary: "Create a new user"
      operationId: "createUser"
      requestBody:  # The request body
        content: 
          application/json: 
            schema: 
              $ref: "#/components/schemas/User"
      responses: 
        '201': 
          description: "User created."

components:  # Components for reuse in the specification
  schemas:  # Schema definitions
    User:  # A schema
      type: "object"  # The type of the schema
      properties:  # The properties of the schema
        id: 
          type: "integer"
        name: 
          type: "string"