## Minimal Document Structure

* openapi: version of the OAS. e.g. "3.1.0"
* info: provides metadata about the API
* paths: describes each of the endpoints in the API

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "The API",
    "version": "0.1.0"
  },
  "paths": {
  }
}
```

## API Endpoints (paths)

* "paths": is an object with the route path as the key.
  * http method: the http method for each path that the path responds to
  * "responses" is an object with http status codes for each key.

```json
{
  "paths": {
    "/users" {
      "get": {
        "summary": "List all the users",
        "description": "List all the users",
        "parameters": [
          {
            "in": "query",
            "name": "q",
            "schema": {
              "type": "string",
              "minimum": 2,
              "maximum": 256
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
            }
          }
        }
      },
      "post": {
        "summary": "create a user",
        "description": "create a user",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "username": "string",
                  "email": "string"
                }
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "No Content",
          },
        }
      }
    }
  }
}
```

## Content

The `content` field in each response is an object with keys for each media type
that the endpoint can be returned as.

* "content": object with keys for each media type
  * media type: the shape of each response for the media type

```json
{
  "content": {
    "application/json": {
      "schema": {
        "type": "array",
        "minItems": 0,
        "maxItems": 12,
        "items": {
          "type": "object",
          "properties": {
            "id": "integer",
            "username": "string",
            "email": "string"
          }
        }
      }
    },
    "text/html": {
      "schema": {
      }
    }
  }
}
```

## Schema

The schema object defines the shape of the response via [JSON schema][1].

```json
"schema": {
  "type": "array",
  "minItems": 0,
  "maxItems": 12,
  "items": {
    "type": "object",
    "properties": {
      "id": "integer",
      "username": "string",
      "email": "string"
    }
  }
}
```

## Parameter Object

* "in": the location of the parameter
  * "path": parameter is part of the request path
  * "query": parameter is a query string parameter of the request
  * "header": parameter is a header of the request.
* "name": the name of the parameter

```json
{
  "in": "path|query|header",
  "name": "q"
}
```

## Request Body Object

```json
{
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "username": "string",
            "email": "string"
          }
        }
      }
    }
  }
}
```

[1]: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00