OpenAPI

We support OpenAPI versions from 3.0 all the way up including 3.2.

By default, we use OpenAPI 3.1, since tooling such as Swagger, Scalar, and Redoc does not yet fully support the latest specification. You can track the current progress here.

Setting up OpenAPI views

We support:

• Swagger with SwaggerView

• Redoc with RedocView

• Scalar with ScalarView

• Stoplight Elements with StoplightView

• openapi.json with OpenAPIJsonView

• openapi.yaml with OpenAPIYamlView when [openapi] extra is installed

Important

We always recommend installing 'django-modern-rest[openapi]' extra when working with OpenAPI.

Here’s how it works:

urls.py

Show imports... 13 lines hidden

[source]

from django.urls import include

from dmr.openapi import build_schema
from dmr.openapi.views import (
    OpenAPIJsonView,
    RedocView,
    ScalarView,
    StoplightView,
    SwaggerView,
)
from dmr.routing import Router, path
from examples.getting_started.msgspec_controller import UserController

router = Router(
    'api/',
    [
        path('user/', UserController.as_view(), name='users'),
    ],
)
schema = build_schema(router)

urlpatterns = [
    path(router.prefix, include((router.urls, 'your_app'), namespace='api')),
    path('docs/openapi.json/', OpenAPIJsonView.as_view(schema), name='openapi'),
    path('docs/swagger/', SwaggerView.as_view(schema), name='swagger'),
    path('docs/scalar/', ScalarView.as_view(schema), name='scalar'),
    path('docs/redoc/', RedocView.as_view(schema), name='redoc'),
    path('docs/stoplight/', StoplightView.as_view(schema), name='stoplight'),
]

OpenAPI Schema

Preview openapi.json

{
  "components": {
    "schemas": {
      "ErrorDetail": {
        "description": "Base schema for error details description.",
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "type": "array"
          },
          "msg": {
            "type": "string"
          },
          "type": {
            "type": "string"
          }
        },
        "required": [
          "msg"
        ],
        "title": "ErrorDetail",
        "type": "object"
      },
      "ErrorModel": {
        "description": "Default error response schema.\n\nCan be customized.\nSee :ref:`customizing-error-messages` for more details.",
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ErrorDetail"
            },
            "type": "array"
          }
        },
        "required": [
          "detail"
        ],
        "title": "ErrorModel",
        "type": "object"
      },
      "UserCreateModel": {
        "properties": {
          "email": {
            "type": "string"
          }
        },
        "required": [
          "email"
        ],
        "title": "UserCreateModel",
        "type": "object"
      },
      "UserModel": {
        "properties": {
          "email": {
            "type": "string"
          },
          "uid": {
            "format": "uuid",
            "type": "string"
          }
        },
        "required": [
          "email",
          "uid"
        ],
        "title": "UserModel",
        "type": "object"
      }
    },
    "securitySchemes": {}
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/user/": {
      "post": {
        "deprecated": false,
        "operationId": "postUsercontrollerApiUser",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserCreateModel"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserModel"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when request components cannot be parsed"
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        }
      }
    }
  }
}

And then visit https://localhost:8000/docs/swagger/ (or any other renderer) for the interactive docs.

What happens in the example above?

1. We create / take an existing API dmr.routing.Router instance and create an OpenAPI schema from it using build_schema()

2. Next, we define regular Django views that will serve you the API renderers

3. You can modify these views to require auth / role / permissions / etc as all other regular Django views

Important

Make sure that 'dmr' is listed in the INSTALLED_APPS and that static files are enabled, so we can serve you the required static files.

Note

By default Swagger, Redoc, and Scalar use bundled static assets that are shipped with django-modern-rest and served by Django. To switch any renderer to a CDN, configure dmr.settings.Settings.openapi_static_cdn. Only renderers listed in that mapping will use CDN; all others keep using local static files. Exact bundled versions and license texts are documented in licenses/.

You can also modify the exact versions that we use for each tool this way.

Example:

settings.py

>>> from dmr.settings import Settings

>>> DMR_SETTINGS = {
...     Settings.openapi_static_cdn: {
...         # or `@5.32.1`, or whatever other version:
...         'swagger': 'https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.32.0',
...     },
... }

Customizing OpenAPI config

We support customizing dmr.openapi.OpenAPIConfig that will be used for the final schema in two ways:

1. By defining dmr.settings.Settings.openapi_config setting inside DMR_SETTINGS in your settings.py

2. By passing OpenAPIConfig instance into build_schema()

For example, this is how you can change some OpenAPI metadata, including the spec version:

urls.py

Show imports... 14 lines hidden

[source]

from django.urls import include

from dmr.openapi import OpenAPIConfig, build_schema
from dmr.openapi.objects import Server
from dmr.openapi.views import (
    OpenAPIJsonView,
    RedocView,
    ScalarView,
    StoplightView,
    SwaggerView,
)
from dmr.routing import Router, path
from examples.getting_started.msgspec_controller import UserController

router = Router(
    'api/',
    [
        path('user/', UserController.as_view(), name='users'),
    ],
)

config = OpenAPIConfig(
    title='My awesome API',
    version='1.0.0',
    openapi_version='3.2.0',
    servers=[
        Server(url='https://prod.example.com'),
        Server(url='https://dev.example.com'),
    ],
)
schema = build_schema(router, config=config)

urlpatterns = [
    path(router.prefix, include((router.urls, 'your_app'), namespace='api')),
    path('docs/openapi.json/', OpenAPIJsonView.as_view(schema), name='openapi'),
    path('docs/swagger/', SwaggerView.as_view(schema), name='swagger'),
    path('docs/scalar/', ScalarView.as_view(schema), name='scalar'),
    path('docs/redoc/', RedocView.as_view(schema), name='redoc'),
    path('docs/stoplight/', StoplightView.as_view(schema), name='stoplight'),
]

OpenAPI Schema

Preview openapi.json

{
  "components": {
    "schemas": {
      "ErrorDetail": {
        "description": "Base schema for error details description.",
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "type": "array"
          },
          "msg": {
            "type": "string"
          },
          "type": {
            "type": "string"
          }
        },
        "required": [
          "msg"
        ],
        "title": "ErrorDetail",
        "type": "object"
      },
      "ErrorModel": {
        "description": "Default error response schema.\n\nCan be customized.\nSee :ref:`customizing-error-messages` for more details.",
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ErrorDetail"
            },
            "type": "array"
          }
        },
        "required": [
          "detail"
        ],
        "title": "ErrorModel",
        "type": "object"
      },
      "UserCreateModel": {
        "properties": {
          "email": {
            "type": "string"
          }
        },
        "required": [
          "email"
        ],
        "title": "UserCreateModel",
        "type": "object"
      },
      "UserModel": {
        "properties": {
          "email": {
            "type": "string"
          },
          "uid": {
            "format": "uuid",
            "type": "string"
          }
        },
        "required": [
          "email",
          "uid"
        ],
        "title": "UserModel",
        "type": "object"
      }
    },
    "securitySchemes": {}
  },
  "info": {
    "title": "My awesome API",
    "version": "1.0.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/user/": {
      "post": {
        "deprecated": false,
        "operationId": "postUsercontrollerApiUser",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserCreateModel"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserModel"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when request components cannot be parsed"
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://prod.example.com"
    },
    {
      "url": "https://dev.example.com"
    }
  ]
}

Customizing OpenAPI generation

Customizing schema

We delegate all schema generation to the model’s library directly. To do so, we use BaseSchemaGenerator subclasses for different serializers.

To customize a schema, use the native methods.

msgspecpydantic

Docs: https://jcristharif.com/msgspec/jsonschema.html

dtos.py

[source]

from typing import Annotated

import msgspec


class UserModel(msgspec.Struct):
    email: Annotated[
        str,
        msgspec.Meta(extra_json_schema={'example': 'user@example.com'}),
    ]

Note

By default docstring or __doc__ from the model is used as a description.

Customizing path items

Controller allows customizing some metadata for PathItem:

views.py

Show imports... 5 lines hidden

[source]

from dmr import Controller
from dmr.openapi.objects import Server
from dmr.plugins.msgspec import MsgspecSerializer


class UserController(Controller[MsgspecSerializer]):
    description = 'Create new users'
    servers = (
        Server(url='https://example.com'),
        Server(url='https://dev.example.com'),
    )

    def post(self) -> str:
        return 'post'

OpenAPI Schema

Preview openapi.json

{
  "components": {
    "schemas": {
      "ErrorDetail": {
        "description": "Base schema for error details description.",
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "type": "array"
          },
          "msg": {
            "type": "string"
          },
          "type": {
            "type": "string"
          }
        },
        "required": [
          "msg"
        ],
        "title": "ErrorDetail",
        "type": "object"
      },
      "ErrorModel": {
        "description": "Default error response schema.\n\nCan be customized.\nSee :ref:`customizing-error-messages` for more details.",
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ErrorDetail"
            },
            "type": "array"
          }
        },
        "required": [
          "detail"
        ],
        "title": "ErrorModel",
        "type": "object"
      }
    },
    "securitySchemes": {}
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/usercontroller/": {
      "description": "Create new users",
      "post": {
        "deprecated": false,
        "operationId": "postUsercontrollerApiUsercontroller",
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "Created"
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        }
      },
      "servers": [
        {
          "url": "https://example.com"
        },
        {
          "url": "https://dev.example.com"
        }
      ]
    }
  }
}

Note

By default docstring or __doc__ from the controller is used to generate summary and description for the PathItem.

Customizing operation

@modify and @validate can be used to customize the resulting Operation metadata.

views.py

Show imports... 9 lines hidden

[source]

from http import HTTPStatus

from django.http import HttpResponse

from dmr import Controller, ResponseSpec, modify, validate
from dmr.openapi.objects import Server
from dmr.plugins.msgspec import MsgspecSerializer


class UserController(Controller[MsgspecSerializer]):
    @modify(servers=[Server(url='https://example.com')])
    def post(self) -> str:
        return 'post'

    @validate(
        ResponseSpec(status_code=HTTPStatus.OK, return_type=str),
        description='PUT operation description',
        tags=['Public'],
    )
    def put(self) -> HttpResponse:
        return self.to_response('put')

OpenAPI Schema

Preview openapi.json

{
  "components": {
    "schemas": {
      "ErrorDetail": {
        "description": "Base schema for error details description.",
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "type": "array"
          },
          "msg": {
            "type": "string"
          },
          "type": {
            "type": "string"
          }
        },
        "required": [
          "msg"
        ],
        "title": "ErrorDetail",
        "type": "object"
      },
      "ErrorModel": {
        "description": "Default error response schema.\n\nCan be customized.\nSee :ref:`customizing-error-messages` for more details.",
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ErrorDetail"
            },
            "type": "array"
          }
        },
        "required": [
          "detail"
        ],
        "title": "ErrorModel",
        "type": "object"
      }
    },
    "securitySchemes": {}
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/usercontroller/": {
      "post": {
        "deprecated": false,
        "operationId": "postUsercontrollerApiUsercontroller",
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "Created"
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        },
        "servers": [
          {
            "url": "https://example.com"
          }
        ]
      },
      "put": {
        "deprecated": false,
        "description": "PUT operation description",
        "operationId": "putUsercontrollerApiUsercontroller",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "OK"
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        },
        "tags": [
          "Public"
        ]
      }
    }
  }
}

Note

By default docstring or __doc__ from endpoint’s function definition is used to generate summary and description for the Operation.

Customizing parameter

There are different styles and other features that Parameter supports in OpenAPI Parameters.

For example, if you want to change how Query parameter is documented with the help of dmr.openapi.objects.ParameterMetadata annotation:

views.py

Show imports... 9 lines hidden

[source]

from typing import Annotated

import msgspec

from dmr import Controller, Query
from dmr.openapi.objects import ParameterMetadata
from dmr.plugins.msgspec import MsgspecSerializer


class QueryModel(msgspec.Struct):
    search: str
    max_items: int


class UserController(
    Controller[MsgspecSerializer],
):
    def post(
        self,
        parsed_query: Query[
            Annotated[
                QueryModel,
                ParameterMetadata(
                    description='Old way to search things',
                    deprecated=True,
                ),
            ]
        ],
    ) -> str:
        return 'post'

OpenAPI Schema

Preview openapi.json

{
  "components": {
    "schemas": {
      "ErrorDetail": {
        "description": "Base schema for error details description.",
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "type": "array"
          },
          "msg": {
            "type": "string"
          },
          "type": {
            "type": "string"
          }
        },
        "required": [
          "msg"
        ],
        "title": "ErrorDetail",
        "type": "object"
      },
      "ErrorModel": {
        "description": "Default error response schema.\n\nCan be customized.\nSee :ref:`customizing-error-messages` for more details.",
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ErrorDetail"
            },
            "type": "array"
          }
        },
        "required": [
          "detail"
        ],
        "title": "ErrorModel",
        "type": "object"
      }
    },
    "securitySchemes": {}
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/usercontroller/": {
      "post": {
        "deprecated": false,
        "operationId": "postUsercontrollerApiUsercontroller",
        "parameters": [
          {
            "deprecated": true,
            "description": "Old way to search things",
            "in": "query",
            "name": "search",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "deprecated": true,
            "description": "Old way to search things",
            "in": "query",
            "name": "max_items",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when request components cannot be parsed"
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        }
      }
    }
  }
}

Customizing media types

There are different metadata fields, like examples and encoding, that MediaType supports in OpenAPI MediaType.

For example, if you want to change how Body provides examples, you can use dmr.openapi.objects.MediaTypeMetadata annotation:

views.py

Show imports... 9 lines hidden

[source]

from typing import Annotated

import pydantic

from dmr import Body, Controller
from dmr.openapi.objects import MediaTypeMetadata
from dmr.plugins.pydantic import PydanticSerializer


class SearchModel(pydantic.BaseModel):
    search: str
    max_items: int


example = SearchModel(search='example', max_items=10).model_dump(mode='json')


class UserController(
    Controller[PydanticSerializer],
):
    def post(
        self,
        parsed_body: Body[
            Annotated[
                SearchModel,
                MediaTypeMetadata(
                    example=example,
                ),
            ]
        ],
    ) -> str:
        return 'post'

OpenAPI Schema

Preview openapi.json

{
  "components": {
    "schemas": {
      "ErrorDetail": {
        "description": "Base schema for error details description.",
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "title": "Loc",
            "type": "array"
          },
          "msg": {
            "title": "Msg",
            "type": "string"
          },
          "type": {
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "msg"
        ],
        "title": "ErrorDetail",
        "type": "object"
      },
      "ErrorModel": {
        "description": "Default error response schema.\n\nCan be customized.\nSee :ref:`customizing-error-messages` for more details.",
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ErrorDetail"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "required": [
          "detail"
        ],
        "title": "ErrorModel",
        "type": "object"
      },
      "SearchModel": {
        "properties": {
          "max_items": {
            "title": "Max Items",
            "type": "integer"
          },
          "search": {
            "title": "Search",
            "type": "string"
          }
        },
        "required": [
          "search",
          "max_items"
        ],
        "title": "SearchModel",
        "type": "object"
      }
    },
    "securitySchemes": {}
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/usercontroller/": {
      "post": {
        "deprecated": false,
        "operationId": "postUsercontrollerApiUsercontroller",
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "max_items": 10,
                "search": "example"
              },
              "schema": {
                "$ref": "#/components/schemas/SearchModel"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when request components cannot be parsed"
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        }
      }
    }
  }
}

We also support the same way for conditional types:

views.py

Show imports... 12 lines hidden

[source]

from typing import Annotated, TypeAlias

import pydantic

from dmr import Body, Controller
from dmr.negotiation import ContentType, conditional_type
from dmr.openapi.objects import MediaTypeMetadata
from dmr.plugins.msgspec import MsgspecJsonParser
from dmr.plugins.pydantic import PydanticSerializer
from examples.negotiation.negotiation import XmlParser


class _SearchModel(pydantic.BaseModel):
    search: str
    max_items: int


class XmlSearchModel(pydantic.BaseModel):
    search: str


SearchModel: TypeAlias = Annotated[
    _SearchModel,
    MediaTypeMetadata(
        example=_SearchModel(search='example', max_items=10).model_dump(
            mode='json',
        ),
    ),
]


class UserController(
    Controller[PydanticSerializer],
):
    parsers = (MsgspecJsonParser(), XmlParser())

    def post(
        self,
        parsed_body: Body[
            Annotated[
                _SearchModel | XmlSearchModel,
                conditional_type({
                    ContentType.json: SearchModel,
                    ContentType.xml: XmlSearchModel,
                }),
            ],
        ],
    ) -> str:
        return 'post'

OpenAPI Schema

Preview openapi.json

{
  "components": {
    "schemas": {
      "ErrorDetail": {
        "description": "Base schema for error details description.",
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "title": "Loc",
            "type": "array"
          },
          "msg": {
            "title": "Msg",
            "type": "string"
          },
          "type": {
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "msg"
        ],
        "title": "ErrorDetail",
        "type": "object"
      },
      "ErrorModel": {
        "description": "Default error response schema.\n\nCan be customized.\nSee :ref:`customizing-error-messages` for more details.",
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ErrorDetail"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "required": [
          "detail"
        ],
        "title": "ErrorModel",
        "type": "object"
      },
      "XmlSearchModel": {
        "properties": {
          "search": {
            "title": "Search",
            "type": "string"
          }
        },
        "required": [
          "search"
        ],
        "title": "XmlSearchModel",
        "type": "object"
      },
      "_SearchModel": {
        "properties": {
          "max_items": {
            "title": "Max Items",
            "type": "integer"
          },
          "search": {
            "title": "Search",
            "type": "string"
          }
        },
        "required": [
          "search",
          "max_items"
        ],
        "title": "_SearchModel",
        "type": "object"
      }
    },
    "securitySchemes": {}
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/usercontroller/": {
      "post": {
        "deprecated": false,
        "operationId": "postUsercontrollerApiUsercontroller",
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "max_items": 10,
                "search": "example"
              },
              "schema": {
                "$ref": "#/components/schemas/_SearchModel"
              }
            },
            "application/xml": {
              "schema": {
                "$ref": "#/components/schemas/XmlSearchModel"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when request components cannot be parsed"
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        }
      }
    }
  }
}

And for FileMetadata:

views.py

Show imports... 10 lines hidden

[source]

from typing import Annotated

import pydantic

from dmr import Controller, FileMetadata
from dmr.openapi.objects import Encoding, MediaTypeMetadata
from dmr.parsers import MultiPartParser
from dmr.plugins.pydantic import PydanticSerializer


class FileModel(pydantic.BaseModel):
    size: int = pydantic.Field(le=1024 * 5)


class UserUpload(pydantic.BaseModel):
    avatar: FileModel


class UserController(
    Controller[PydanticSerializer],
):
    parsers = (MultiPartParser(),)

    def post(
        self,
        parsed_file_metadata: FileMetadata[
            Annotated[
                UserUpload,
                MediaTypeMetadata(
                    # Note, that this can also inferred from `Literal` type
                    # in `FileModel.content_type` property, but can be set here:
                    encoding={'avatar': Encoding(content_type='image/png')},
                ),
            ]
        ],
    ) -> str:
        return 'post'

OpenAPI Schema

Preview openapi.json

{
  "components": {
    "schemas": {
      "ErrorDetail": {
        "description": "Base schema for error details description.",
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "title": "Loc",
            "type": "array"
          },
          "msg": {
            "title": "Msg",
            "type": "string"
          },
          "type": {
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "msg"
        ],
        "title": "ErrorDetail",
        "type": "object"
      },
      "ErrorModel": {
        "description": "Default error response schema.\n\nCan be customized.\nSee :ref:`customizing-error-messages` for more details.",
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ErrorDetail"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "required": [
          "detail"
        ],
        "title": "ErrorModel",
        "type": "object"
      }
    },
    "securitySchemes": {}
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/usercontroller/": {
      "post": {
        "deprecated": false,
        "operationId": "postUsercontrollerApiUsercontroller",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "encoding": {
                "avatar": {
                  "contentType": "image/png"
                }
              },
              "schema": {
                "properties": {
                  "avatar": {
                    "format": "binary",
                    "type": "string"
                  }
                },
                "required": [
                  "avatar"
                ],
                "title": "UserUpload",
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when request components cannot be parsed"
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        }
      }
    }
  }
}

Customizing response

ResponseSpec supports all the metadata fields that Response has.

Providing an explicit Link for schemathesis stateful API testing would look like so:

views.py

Show imports... 11 lines hidden

[source]

import uuid
from http import HTTPStatus

import msgspec
from django.http import HttpResponse

from dmr import Controller, ResponseSpec, modify, validate
from dmr.openapi.objects import Link
from dmr.plugins.msgspec import MsgspecSerializer


class UserModel(msgspec.Struct):
    uid: uuid.UUID


class UserController(Controller[MsgspecSerializer]):
    @modify(
        response_description='This is a description for your response',
        links={
            'GetUser': Link(
                operation_id='getUser',
                parameters={'userId': '$response.body#/uid'},
            ),
        },
    )
    def post(self) -> UserModel:
        return UserModel(uid=uuid.uuid4())

    @validate(
        ResponseSpec(
            status_code=HTTPStatus.OK,
            return_type=UserModel,
            links={
                'GetUser': Link(
                    operation_id='getUser',
                    parameters={'userId': '$response.body#/uid'},
                ),
            },
        ),
    )
    def put(self) -> HttpResponse:
        return self.to_response(UserModel(uid=uuid.uuid4()))

OpenAPI Schema

Preview openapi.json

{
  "components": {
    "schemas": {
      "ErrorDetail": {
        "description": "Base schema for error details description.",
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "type": "array"
          },
          "msg": {
            "type": "string"
          },
          "type": {
            "type": "string"
          }
        },
        "required": [
          "msg"
        ],
        "title": "ErrorDetail",
        "type": "object"
      },
      "ErrorModel": {
        "description": "Default error response schema.\n\nCan be customized.\nSee :ref:`customizing-error-messages` for more details.",
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ErrorDetail"
            },
            "type": "array"
          }
        },
        "required": [
          "detail"
        ],
        "title": "ErrorModel",
        "type": "object"
      },
      "UserModel": {
        "properties": {
          "uid": {
            "format": "uuid",
            "type": "string"
          }
        },
        "required": [
          "uid"
        ],
        "title": "UserModel",
        "type": "object"
      }
    },
    "securitySchemes": {}
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/usercontroller/": {
      "post": {
        "deprecated": false,
        "operationId": "postUsercontrollerApiUsercontroller",
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserModel"
                }
              }
            },
            "description": "This is a description for your response",
            "links": {
              "GetUser": {
                "operationId": "getUser",
                "parameters": {
                  "userId": "$response.body#/uid"
                }
              }
            }
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        }
      },
      "put": {
        "deprecated": false,
        "operationId": "putUsercontrollerApiUsercontroller",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserModel"
                }
              }
            },
            "description": "OK",
            "links": {
              "GetUser": {
                "operationId": "getUser",
                "parameters": {
                  "userId": "$response.body#/uid"
                }
              }
            }
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        }
      }
    }
  }
}

Examples generation

If you installed 'django-modern-rest[openapi]' extra and enabled openapi_examples_seed setting, we will generate missing examples in your OpenAPI schemas using polyfactory.

They will not have the best data quality, since they are clearly autogenerated from fake data, but sometimes it is better than nothing.

views.py

Show imports... 8 lines hidden

[source]

import uuid

import msgspec

from dmr import Controller, Query
from dmr.plugins.msgspec import MsgspecSerializer


class QueryModel(msgspec.Struct):
    search: str
    max_items: int


class UserModel(msgspec.Struct):
    uid: uuid.UUID
    username: str


class UserController(
    Controller[MsgspecSerializer],
):
    def post(self, parsed_query: Query[QueryModel]) -> UserModel:
        return UserModel(uid=uuid.uuid4(), username='example')

OpenAPI Schema

Preview openapi.json

{
  "components": {
    "schemas": {
      "ErrorDetail": {
        "description": "Base schema for error details description.",
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "type": "array"
          },
          "msg": {
            "type": "string"
          },
          "type": {
            "type": "string"
          }
        },
        "required": [
          "msg"
        ],
        "title": "ErrorDetail",
        "type": "object"
      },
      "ErrorModel": {
        "description": "Default error response schema.\n\nCan be customized.\nSee :ref:`customizing-error-messages` for more details.",
        "example": {
          "detail": [
            {
              "loc": [
                "vbzQIBShDtFfOfiPXwvm"
              ],
              "msg": "gNZYFcagWptUqCwdERil"
            }
          ]
        },
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ErrorDetail"
            },
            "type": "array"
          }
        },
        "required": [
          "detail"
        ],
        "title": "ErrorModel",
        "type": "object"
      },
      "UserModel": {
        "example": {
          "uid": "7b89296c-6dcb-4c50-8857-7eb1924770d3",
          "username": "EkQQHiBrmXZcSFtoJxJI"
        },
        "properties": {
          "uid": {
            "format": "uuid",
            "type": "string"
          },
          "username": {
            "type": "string"
          }
        },
        "required": [
          "uid",
          "username"
        ],
        "title": "UserModel",
        "type": "object"
      }
    },
    "securitySchemes": {}
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/usercontroller/": {
      "post": {
        "deprecated": false,
        "operationId": "postUsercontrollerApiUsercontroller",
        "parameters": [
          {
            "deprecated": false,
            "in": "query",
            "name": "search",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "deprecated": false,
            "in": "query",
            "name": "max_items",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserModel"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when request components cannot be parsed"
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        }
      }
    }
  }
}

Important

However, we recommend adding semantic named examples by hand.

Top level API

This is how OpenAPI spec is generated, top level overview:

        ---
config:
  theme: forest

---
graph
    Start[build_schema] --> Router[Router];
    Router -->|for each controller| Controller[Controller.get_path_item];
    Router -->|for each defined auth| SecurityScheme[Auth.security_scheme];
    Controller -->|for each endpoint| Endpoint[Endpoint.get_schema];
    Endpoint -->|for each component| ComponentParser[ComponentParser.get_schema]
    Endpoint -->|for each response| ResponseSpec[ResponseSpec.get_schema];
    Endpoint -->|for each used auth| SecurityRequirement[Auth.security_requirement];
    ComponentParser -->|for each schema| Schema[serializer.schema_generator.get_schema];
    ResponseSpec -->|for each schema| Schema[serializer.schema_generator.get_schema];
    

OpenAPI spec generation

We have several major design principles that define our API:

1. Regular user-facing objects must know how to build the OpenAPI schema. For example: Endpoint, Controller, and Router all know how to build the spec for themselves. Since they are user-facing, it is easy to modify how the schema generation works if needed

2. All model schemas must be directly generated by their libraries. We don’t do anything with the JSON Schema that is generated by pydantic or msgspec. They can do a better job than we do. However, their schemas still can be customized. See PydanticSchemaGenerator and MsgspecSchemaGenerator

APIs for schema overrides

Useful APIs for users to override:

• dmr.openapi.build_schema() to change how OpenAPIConfig and OpenAPIContext are generated

• dmr.routing.Router.get_schema() to change how OpenAPI and Components are generated

• dmr.controller.Controller.get_path_item() to change how PathItem objects are generated

• dmr.endpoint.Endpoint.get_schema() to change how Operation is generated

• dmr.components.ComponentParser.get_schema() to change how Parameter objects are generated

• dmr.metadata.ResponseSpec.get_schema() to change how Response objects are generated

• dmr.security.SyncAuth.security_schemes() and dmr.security.SyncAuth.security_requirement to change how SecurityScheme and requirements are generated

API Reference

This is the API every user needs:

dmr.openapi.build_schema(router: Router, *, context: OpenAPIContext) → OpenAPI

dmr.openapi.build_schema(router: Router, *, config: OpenAPIConfig | None = None) → OpenAPI

Build OpenAPI schema.

Parameters:

• router – Router that contains all API endpoints and all controllers.

• context – OpenAPI context with all the builder tools.

• config – Optional configuration of OpenAPI metadata. Can be None, in this case we fetch OpenAPI config from settings.

class dmr.openapi.OpenAPIConfig(*, title: str, version: str, openapi_version: str = '3.1.0', summary: str | None = None, description: str | None = None, terms_of_service: str | None = None, contact: Contact | None = None, external_docs: ExternalDocumentation | None = None, security: list[dict[str, list[str]]] | None = None, license: License | None = None, components: Components | list[Components] | None = None, servers: list[Server] | None = None, tags: list[Tag] | None = None, webhooks: dict[str, PathItem | Reference] | None = None)

Configuration class for customizing OpenAPI specification metadata.

This class provides a way to configure various aspects of the OpenAPI specification that will be generated for your API documentation. It allows you to customize the API information, contact details, licensing, security requirements, and other metadata that appears in the generated OpenAPI spec.

class dmr.openapi.OpenAPIContext(config: OpenAPIConfig)

Context for OpenAPI specification generation.

Maintains shared state and generators used across the OpenAPI generation process. Provides access to different generators.

register_schema(annotation: Any, schema: Schema | Reference | SchemaCallback, *, override: bool = False) → None

Register top-level annotation resolution into an OpenAPI schema.

You can pass either a schema object itself, a reference, or a callback that returns schema, reference, or None to fallback to the default schema resolution process.

Warning

This only works for the top-level annotations with direct matches. For example: when you register User to have a specific schema, it will take effect only in cases where User is used directly. list[User] will use the default serializer schema resolution strategy.

All other objects that are only used if you decide to customize the schema are listed in OpenAPI Reference.