# Install the PyYAML library for pretty-printing the OpenAPI schema
pip install pyyaml
```

## Pydantic to OpenAPI document walkthrough

Let's follow a step-by-step process to generate an OpenAPI document from a Pydantic model without any additional libraries.

### Defining a simple Pydantic model

Create a new Python file called `models.py` and define a simple Pydantic model.

In this example, we define a Pydantic model called `Pet` with three fields: `id`, `name`, and `breed`. The `id` field is an integer, and the `name` and `breed` fields are strings.

```python
from pydantic import BaseModel


class Pet(BaseModel):
    id: int
    name: str
    breed: str
```

### Generating a JSON schema for the Pydantic model

Add a new function called `print_json_schema` to the `models.py` file that prints the JSON schema for the `Pet` model.

This function uses the `model_json_schema` method provided by Pydantic to generate the JSON schema, which Python then prints to the console as YAML. We use YAML for readability, but the output is still a valid JSON schema.

```python
import yaml
from pydantic import BaseModel


class Pet(BaseModel):
    id: int
    name: str
    breed: str


def print_json_schema():
    print(yaml.dump(Pet.model_json_schema()))


if __name__ == "__main__":
    print_json_schema()
```

Run `python models.py` to generate the JSON schema for the `Pet` model and print it as YAML:

```yaml
properties:
  breed:
    title: Breed
    type: string
  id:
    title: Id
    type: integer
  name:
    title: Name
    type: string
required:
  - id
  - name
  - breed
title: Pet
type: object
```

### Multiple Pydantic models

Let's add another Pydantic model called `Owner` to the `models.py` file.

The `Owner` model has two fields: `id` and `name`. Both fields are integers. Additionally, the `Owner` model has a list of `Pet` objects.

```python
import yaml
from pydantic import BaseModel


class Pet(BaseModel):
    id: int
    name: str
    breed: str


class Owner(BaseModel):
    id: int
    name: str
    pets: list[Pet]


def print_json_schema():
    print(yaml.dump(Pet.model_json_schema()))


if __name__ == "__main__":
    print_json_schema()
```

### Generating a JSON schema for multiple Pydantic models

Update the `print_json_schema` function to print the JSON schema for both the `Pet` and `Owner` models.

Note that we're now calling the [`models_json_schema`](https://docs.pydantic.dev/2.7/api/json_schema/#pydantic.json_schema.models_json_schema) function from `pydantic.json_schema` instead of the `model_json_schema` method.

```python
import yaml
from pydantic import BaseModel
from pydantic.json_schema import models_json_schema


class Pet(BaseModel):
    id: int
    name: str
    breed: str


class Owner(BaseModel):
    id: int
    name: str
    pets: list[Pet]


def print_json_schema(models):
    _, schemas = models_json_schema(
        [(model, "validation") for model in models],
    )
    print(yaml.dump(schemas))


if __name__ == "__main__":
    print_json_schema([Pet, Owner])
```

Run `python models.py` to generate the JSON schema for both the `Pet` and `Owner` models and print it as YAML:

```yaml
$defs:
  Owner:
    properties:
      id:
        title: Id
        type: integer
      name:
        title: Name
        type: string
      pets:
        items:
          $ref: "#/$defs/Pet"
        title: Pets
        type: array
    required:
      - id
      - name
      - pets
    title: Owner
    type: object
  Pet:
    properties:
      breed:
        title: Breed
        type: string
      id:
        title: Id
        type: integer
      name:
        title: Name
        type: string
    required:
      - id
      - name
      - breed
    title: Pet
    type: object
```

The generated schema includes definitions for both the `Pet` and `Owner` models. The `Owner` model has a reference to the `Pet` model, indicating that the `Owner` model contains a list of `Pet` objects.

Note that the root of the schema includes a `$defs` key that contains the definitions for both models, and the `Owner` model references the `Pet` model using the `$ref` keyword.

### Customizing Pydantic JSON schema generation

Let's customize the generated JSON schema to reference the `Pet` model using the `#/components/schemas` path instead of `$defs`.

We'll use the `ref_template` parameter of the `models_json_schema` function to specify the reference template.

```python
import yaml
from pydantic import BaseModel
from pydantic.json_schema import models_json_schema


class Pet(BaseModel):
    id: int
    name: str
    breed: str


class Owner(BaseModel):
    id: int
    name: str
    pets: list[Pet]


def print_json_schema(models):
    _, schemas = models_json_schema(
        [(model, "validation") for model in models],
        ref_template="#/components/schemas/{model}",
    )
    print(yaml.dump(schemas))


if __name__ == "__main__":
    print_json_schema([Pet, Owner])
```

Next, we'll update the `print_json_schema` function to print a JSON schema that resembles an OpenAPI document's `components` section.

```python
import yaml
from pydantic import BaseModel
from pydantic.json_schema import models_json_schema


class Pet(BaseModel):
    id: int
    name: str
    breed: str


class Owner(BaseModel):
    id: int
    name: str
    pets: list[Pet]


def print_json_schema(models):
    _, schemas = models_json_schema(
        [(model, "validation") for model in models],
        ref_template="#/components/schemas/{model}",
    )
    openapi_schema = {
        "components": {
            "schemas": schemas.get('$defs'),
        }
    }
    print(yaml.dump(openapi_schema))


if __name__ == "__main__":
    print_json_schema([Pet, Owner])
```

Run `python models.py` to generate the OpenAPI document for both the `Pet` and `Owner` models.

The generated OpenAPI document includes the `components` section, with definitions for both the `Pet` and `Owner` models.

```yaml
components:
  schemas:
    Owner:
      properties:
        id:
          title: Id
          type: integer
        name:
          title: Name
          type: string
        pets:
          items:
            $ref: "#/components/schemas/Pet"
          title: Pets
          type: array
      required:
        - id
        - name
        - pets
      title: Owner
      type: object
    Pet:
      properties:
        breed:
          title: Breed
          type: string
        id:
          title: Id
          type: integer
        name:
          title: Name
          type: string
      required:
        - id
        - name
        - breed
      title: Pet
      type: object
```

The JSON schema we generated resembles an OpenAPI document's `components` section, but to generate a valid OpenAPI document, we need to add the `openapi` and `info` sections.

Edit the `print_json_schema` function in `models.py` to include the `openapi` and `info` sections in the generated OpenAPI document.

```python
import yaml
from pydantic import BaseModel
from pydantic.json_schema import models_json_schema


class Pet(BaseModel):
    id: int
    name: str
    breed: str


class Owner(BaseModel):
    id: int
    name: str
    pets: list[Pet]


def print_json_schema(models):
    _, schemas = models_json_schema(
        [(model, "validation") for model in models],
        ref_template="#/components/schemas/{model}",
    )
    openapi_schema = {
        "openapi": "3.1.0",
        "info": {
            "title": "Pet Sitter API",
            "version": "0.0.1",
        },
        "components": {
            "schemas": schemas.get('$defs'),
        }
    }
    print(yaml.dump(openapi_schema))


if __name__ == "__main__":
    print_json_schema([Pet, Owner])
```

Run `python models.py` to generate the complete OpenAPI document for both the `Pet` and `Owner` models.

The generated OpenAPI document includes the `openapi`, `info`, and `components` sections with definitions for both the `Pet` and `Owner` models.

```yaml
openapi: 3.1.0
info:
  title: Pet Sitter API
  version: 0.0.1
components:
  schemas:
    Owner:
      properties:
        id:
          title: Id
          type: integer
        name:
          title: Name
          type: string
        pets:
          items:
            $ref: "#/components/schemas/Pet"
          title: Pets
          type: array
      required:
        - id
        - name
        - pets
      title: Owner
      type: object
    Pet:
      properties:
        id:
          title: Id
          type: integer
        name:
          title: Name
          type: string
        breed:
          title: Breed
          type: string
      required:
        - id
        - name
        - breed
      title: Pet
      type: object
```

Now we have a complete OpenAPI document that we can use to generate SDK clients for our API. However, the generated OpenAPI document does not contain descriptions or example values for the models. We can add these details to the Pydantic models to improve the generated OpenAPI document.

### Adding descriptions to Pydantic models

Let's add docstrings to the `Pet` and `Owner` models to include additional information in the generated OpenAPI document.

```python
import yaml
from pydantic import BaseModel
from pydantic.json_schema import models_json_schema


class Pet(BaseModel):
    """
    A Pet in the system.

    ID is unique.
    Can have multiple owners.
    """

    id: int
    name: str
    breed: str


class Owner(BaseModel):
    """
    An Owner of Pets in the system.

    ID is unique.
    Can have multiple pets.
    """

    id: int
    name: str
    pets: list[Pet]


def print_json_schema(models):
    _, schemas = models_json_schema(
        [(model, "validation") for model in models],
        ref_template="#/components/schemas/{model}",
    )
    openapi_schema = {
        "openapi": "3.1.0",
        "info": {
            "title": "Pet Sitter API",
            "version": "0.0.1",
        },
        "components": {
            "schemas": schemas.get("$defs"),
        },
    }
    print(yaml.dump(openapi_schema, sort_keys=False))


if __name__ == "__main__":
    print_json_schema([Pet, Owner])
```

If we run `python models.py`, we see that our `Owner` schema now includes a description field, derived from the docstring we added to the `Owner` Pydantic model.

```yaml
openapi: 3.1.0
info:
  title: Pet Sitter API
  version: 0.0.1
components:
  schemas:
    Owner:
      description: "An Owner of Pets in the system.


        ID is unique.

        Can have multiple pets."
      properties:
        id:
          title: Id
          type: integer
        name:
          title: Name
          type: string
        pets:
          items:
            $ref: "#/components/schemas/Pet"
          title: Pets
          type: array
      required:
        - id
        - name
        - pets
      title: Owner
      type: object
    Pet:
      description: "A Pet in the system.


        ID is unique.

        Can have multiple owners."
      properties:
        id:
          title: Id
          type: integer
        name:
          title: Name
          type: string
        breed:
          title: Breed
          type: string
      required:
        - id
        - name
        - breed
      title: Pet
      type: object
```

The `Pet` schema now also includes a description field, derived from the docstring we added to the `Pet` Pydantic model.

### Adding OpenAPI titles and descriptions to Pydantic fields

Let's add titles and descriptions to the fields of the `Pet` and `Owner` models to include additional information in the generated OpenAPI document.

We'll use the `Field` class from Pydantic to add descriptions to the fields.

```python
import yaml
from pydantic import BaseModel, Field
from pydantic.json_schema import models_json_schema


class Pet(BaseModel):
    """
    A Pet in the system.

    ID is unique.
    Can have multiple owners.
    """

    id: int = Field(..., title="Pet ID", description="The pet's unique identifier")
    name: str = Field(..., title="Pet Name", description="Name of the pet")
    breed: str = Field(..., title="Pet Breed", description="Breed of the pet")


class Owner(BaseModel):
    """
    An Owner of Pets in the system.

    ID is unique.
    Can have multiple pets.
    """

    id: int = Field(..., title="Owner ID", description="Owner's unique identifier")
    name: str = Field(..., title="Owner Name", description="The owner's full name")
    pets: list[Pet] = Field(
        ..., title="Owner's Pets", description="The pets that belong to this owner"
    )


def print_json_schema(models):
    _, schemas = models_json_schema(
        [(model, "validation") for model in models],
        ref_template="#/components/schemas/{model}",
    )
    openapi_schema = {
        "openapi": "3.1.0",
        "info": {
            "title": "Pet Sitter API",
            "version": "0.0.1",
        },
        "components": {
            "schemas": schemas.get("$defs"),
        },
    }
    print(yaml.dump(openapi_schema, sort_keys=False))


if __name__ == "__main__":
    print_json_schema([Pet, Owner])
```

If we run `python models.py`, we see that our `Pet` schema now includes descriptions for each field.

```yaml
openapi: 3.1.0
info:
  title: Pet Sitter API
  version: 0.0.1
components:
  schemas:
    Owner:
      description: "An Owner of Pets in the system.


        ID is unique.

        Can have multiple pets."
      properties:
        id:
          description: Owner's unique identifier
          title: Owner ID
          type: integer
        name:
          description: The owner's full name
          title: Owner Name
          type: string
        pets:
          description: The pets that belong to this owner
          items:
            $ref: "#/components/schemas/Pet"
          title: Owner's Pets
          type: array
      required:
        - id
        - name
        - pets
      title: Owner
      type: object
    Pet:
      description: "A Pet in the system.


        ID is unique.

        Can have multiple owners."
      properties:
        id:
          description: The pet's unique identifier
          title: Pet ID
          type: integer
        name:
          description: Name of the pet
          title: Pet Name
          type: string
        breed:
          description: Breed of the pet
          title: Pet Breed
          type: string
      required:
        - id
        - name
        - breed
      title: Pet
      type: object
```

### Adding OpenAPI example values to Pydantic models

Examples help API users understand your API's data structures, and some SDK and documentation generators use OpenAPI example values to generate useful code snippets and documentation.

Let's add example values to the `Pet` and `Owner` Pydantic models. Once again, we'll use the `Field` class from Pydantic to add example values to the fields.

Note that the examples are added as a list per field, using the `examples` parameter.

```python
import yaml
from pydantic import BaseModel, Field
from pydantic.json_schema import models_json_schema


class Pet(BaseModel):
    """
    A Pet in the system.

    ID is unique.
    Can have multiple owners.
    """

    id: int = Field(
        ...,
        title="Pet ID",
        description="The pet's unique identifier",
        examples=[1],
    )
    name: str = Field(
        ...,
        title="Pet Name",
        description="Name of the pet",
        examples=["Fido"],
    )
    breed: str = Field(
        ...,
        title="Pet Breed",
        description="Breed of the pet",
        examples=["Golden Retriever", "Siamese", "Parakeet"],
    )


class Owner(BaseModel):
    """
    An Owner of Pets in the system.

    ID is unique.
    Can have multiple pets.
    """

    id: int = Field(
        ...,
        title="Owner ID",
        description="Owner's unique identifier",
        examples=[1],
    )
    name: str = Field(
        ...,
        title="Owner Name",
        description="The owner's full name",
        examples=["John Doe"],
    )
    pets: list[Pet] = Field(
        ...,
        title="Owner's Pets",
        description="The pets that belong to this owner",
        examples=[{"id": 1}],
    )


def print_json_schema(models):
    _, schemas = models_json_schema(
        [(model, "validation") for model in models],
        ref_template="#/components/schemas/{model}",
    )
    openapi_schema = {
        "openapi": "3.1.0",
        "info": {
            "title": "Pet Sitter API",
            "version": "0.0.1",
        },
        "components": {
            "schemas": schemas.get("$defs"),
        },
    }
    print(yaml.dump(openapi_schema, sort_keys=False))


if __name__ == "__main__":
    print_json_schema([Pet, Owner])
```

If we run `python models.py`, we see that our `Pet` schema now includes example values for each field.

```yaml
openapi: 3.1.0
info:
  title: Pet Sitter API
  version: 0.0.1
components:
  schemas:
    Owner:
      description: "An Owner of Pets in the system.


        ID is unique.

        Can have multiple pets."
      properties:
        id:
          description: Owner's unique identifier
          examples:
            - 1
          title: Owner ID
          type: integer
        name:
          description: The owner's full name
          examples:
            - John Doe
          title: Owner Name
          type: string
        pets:
          description: The pets that belong to this owner
          examples:
            - id: 1
          items:
            $ref: "#/components/schemas/Pet"
          title: Owner's Pets
          type: array
      required:
        - id
        - name
        - pets
      title: Owner
      type: object
    Pet:
      description: "A Pet in the system.


        ID is unique.

        Can have multiple owners."
      properties:
        id:
          description: The pet's unique identifier
          examples:
            - 1
          title: Pet ID
          type: integer
        name:
          description: Name of the pet
          examples:
            - Fido
          title: Pet Name
          type: string
        breed:
          description: Breed of the pet
          examples:
            - Golden Retriever
            - Siamese
            - Parakeet
          title: Pet Breed
          type: string
      required:
        - id
        - name
        - breed
      title: Pet
      type: object
```

### Marking fields as optional in Pydantic models

By default, Pydantic marks all fields as required. You can mark a field as optional by setting the `default` parameter to `None`.

Let's mark the `breed` field in the `Pet` model as optional by setting the `default` parameter to `None`.

```python
import yaml
from pydantic import BaseModel, Field
from pydantic.json_schema import models_json_schema


class Pet(BaseModel):
    """
    A Pet in the system.

    ID is unique.
    Can have multiple owners.
    """

    id: int = Field(
        ...,
        title="Pet ID",
        description="The pet's unique identifier",
        examples=[1],
    )
    name: str = Field(
        ...,
        title="Pet Name",
        description="Name of the pet",
        examples=["Fido"],
    )
    breed: str | None = Field(
        None,
        title="Pet Breed",
        description="Breed of the pet",
        examples=["Golden Retriever", "Siamese", "Parakeet"],
    )


class Owner(BaseModel):
    """
    An Owner of Pets in the system.

    ID is unique.
    Can have multiple pets.
    """

    id: int = Field(
        ...,
        title="Owner ID",
        description="Owner's unique identifier",
        examples=[1],
    )
    name: str = Field(
        ...,
        title="Owner Name",
        description="The owner's full name",
        examples=["John Doe"],
    )
    pets: list[Pet] = Field(
        ...,
        title="Owner's Pets",
        description="The pets that belong to this owner",
        examples=[{"id": 1}],
    )


def print_json_schema(models):
    _, schemas = models_json_schema(
        [(model, "validation") for model in models],
        ref_template="#/components/schemas/{model}",
    )
    openapi_schema = {
        "openapi": "3.1.0",
        "info": {
            "title": "Pet Sitter API",
            "version": "0.0.1",
        },
        "components": {
            "schemas": schemas.get("$defs"),
        },
    }
    print(yaml.dump(openapi_schema, sort_keys=False))


if __name__ == "__main__":
    print_json_schema([Pet, Owner])
```

If we run `python models.py`, we see that the `breed` field in the `Pet` schema now has two types: `string` and `null`, and it has been removed from the `required` list. Only `id` and `name` are required fields after marking `breed` as optional.

```yaml
openapi: 3.1.0
info:
  title: Pet Sitter API
  version: 0.0.1
components:
  schemas:
    Owner:
      description: "An Owner of Pets in the system.


        ID is unique.

        Can have multiple pets."
      properties:
        id:
          description: Owner's unique identifier
          examples:
            - 1
          title: Owner ID
          type: integer
        name:
          description: The owner's full name
          examples:
            - John Doe
          title: Owner Name
          type: string
        pets:
          description: The pets that belong to this owner
          examples:
            - id: 1
          items:
            $ref: "#/components/schemas/Pet"
          title: Owner's Pets
          type: array
      required:
        - id
        - name
        - pets
      title: Owner
      type: object
    Pet:
      description: "A Pet in the system.


        ID is unique.

        Can have multiple owners."
      properties:
        id:
          description: The pet's unique identifier
          examples:
            - 1
          title: Pet ID
          type: integer
        name:
          description: Name of the pet
          examples:
            - Fido
          title: Pet Name
          type: string
        breed:
          anyOf:
            - type: string
            - type: "null"
          default: null
          description: Breed of the pet
          examples:
            - Golden Retriever
            - Siamese
            - Parakeet
          title: Pet Breed
      required:
        - id
        - name
      title: Pet
      type: object
```

### Adding enums to OpenAPI using Pydantic models

Enums in OpenAPI are useful for defining a set of possible values for a field.

Let's add an enum called `PetType` to the `Pet` model to represent different types of pets.

```python
from enum import StrEnum
import yaml
from pydantic import BaseModel, Field
from pydantic.json_schema import models_json_schema


class PetType(StrEnum):
    """
    An enumeration of pet types.
    """

    DOG = "dog"
    CAT = "cat"
    BIRD = "bird"


class Pet(BaseModel):
    """
    A Pet in the system.

    ID is unique.
    Can have multiple owners.
    """

    pet_type: PetType = Field(
        ...,
        title="Pet Type",
        description="Type of pet",
        examples=["dog", "cat", "bird"],
    )
    id: int = Field(
        ...,
        title="Pet ID",
        description="The pet's unique identifier",
        examples=[1],
    )
    name: str = Field(
        ...,
        title="Pet Name",
        description="Name of the pet",
        examples=["Fido"],
    )
    breed: str | None = Field(
        None,
        title="Pet Breed",
        description="Breed of the pet",
        examples=["Golden Retriever", "Siamese", "Parakeet"],
    )


class Owner(BaseModel):
    """
    An Owner of Pets in the system.

    ID is unique.
    Can have multiple pets.
    """

    id: int = Field(
        ...,
        title="Owner ID",
        description="Owner's unique identifier",
        examples=[1],
    )
    name: str = Field(
        ...,
        title="Owner Name",
        description="The owner's full name",
        examples=["John Doe"],
    )
    pets: list[Pet] = Field(
        ...,
        title="Owner's Pets",
        description="The pets that belong to this owner",
        examples=[{"id": 1}],
    )


def print_json_schema(models):
    _, schemas = models_json_schema(
        [(model, "validation") for model in models],
        ref_template="#/components/schemas/{model}",
    )
    openapi_schema = {
        "openapi": "3.1.0",
        "info": {
            "title": "Pet Sitter API",
            "version": "0.0.1",
        },
        "components": {
            "schemas": schemas.get("$defs"),
        },
    }
    print(yaml.dump(openapi_schema, sort_keys=False))


if __name__ == "__main__":
    print_json_schema([Pet, Owner])
```

In our generated OpenAPI document, we have a new `pet_type` field in the `Pet` schema.

```yaml
openapi: 3.1.0
info:
  title: Pet Sitter API
  version: 0.0.1
components:
  schemas:
    Owner:
      description: "An Owner of Pets in the system.


        ID is unique.

        Can have multiple pets."
      properties:
        id:
          description: Owner's unique identifier
          examples:
            - 1
          title: Owner ID
          type: integer
        name:
          description: The owner's full name
          examples:
            - John Doe
          title: Owner Name
          type: string
        pets:
          description: The pets that belong to this owner
          examples:
            - id: 1
          items:
            $ref: "#/components/schemas/Pet"
          title: Owner's Pets
          type: array
      required:
        - id
        - name
        - pets
      title: Owner
      type: object
    Pet:
      description: "A Pet in the system.


        ID is unique.

        Can have multiple owners."
      properties:
        pet_type:
          allOf:
            - $ref: "#/components/schemas/PetType"
          description: Type of pet
          examples:
            - dog
            - cat
            - bird
          title: Pet Type
        id:
          description: The pet's unique identifier
          examples:
            - 1
          title: Pet ID
          type: integer
        name:
          description: Name of the pet
          examples:
            - Fido
          title: Pet Name
          type: string
        breed:
          anyOf:
            - type: string
            - type: "null"
          default: null
          description: Breed of the pet
          examples:
            - Golden Retriever
            - Siamese
            - Parakeet
          title: Pet Breed
      required:
        - pet_type
        - id
        - name
      title: Pet
      type: object
    PetType:
      description: An enumeration of pet types.
      enum:
        - dog
        - cat
        - bird
      title: PetType
      type: string
```

This enum is represented as a separate schema in the OpenAPI document.

## Adding paths and operations to the OpenAPI document

Now that we have generated an OpenAPI document from our Pydantic models, we can use the schema to generate SDK clients for our API.

However, the OpenAPI document we generated, while valid, does not include the `paths` section, which defines the API endpoints and operations.

When using Pydantic with FastAPI, you can define your API endpoints and operations directly in your FastAPI application. [FastAPI automatically generates the OpenAPI document for your API](/openapi/frameworks/fastapi#speakeasy-integration), including the `paths` section.

Let's see how we can define API endpoints and operations in a framework-agnostic way and add them to the OpenAPI document.

### Installing openapi-pydantic

We'll use the [`openapi-pydantic`](https://github.com/mike-oakley/openapi-pydantic/) library to define a complete OpenAPI document with paths and operations.

The benefit of using `openapi-pydantic` is that it allows you to define the API endpoints and operations in a Python dictionary while still getting the benefit of Pydantic's IDE support and type checking.

The library includes convenience methods to convert Pydantic models to OpenAPI document components and to add them to the OpenAPI document.

Install the `openapi-pydantic` library:

```bash filename="Terminal"
pip install openapi-pydantic
```

### Defining API endpoints

Create a new file called `api.py` to define the API endpoints using the `openapi-pydantic` library:

```python filename="api.py"
from typing import List
import yaml
from pydantic import BaseModel, Field
from openapi_pydantic.v3 import OpenAPI, Info, PathItem, Operation
from openapi_pydantic.util import PydanticSchema, construct_open_api_with_schema_class
from models import Pet, Owner