OpenAPI

We support OpenAPI versions from 3.0.0 through 3.2.0.

Note

By default, we use OpenAPI 3.1.0, since tooling such as Swagger, Scalar, Redoc, and Stoplight 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 recommend installing 'django-modern-rest[openapi]' when working with OpenAPI. It enables schema validation, adds OpenAPIYamlView, and supports automatic example generation.

Here’s how it works:

urls.py

Show imports... 14 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.openapi.views.yaml import OpenAPIYamlView
from dmr.routing import Router, path
from examples.getting_started.msgspec_controller import UserController

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

# Build the schema once and reuse it across all docs views.
schema = build_schema(router)

urlpatterns = [
    # Mount the actual API endpoints.
    path(router.prefix, include((router.urls, 'your_app'), namespace='api')),
    # Machine-readable schema outputs for tooling and client generation.
    path(
        'docs/openapi.json/',
        OpenAPIJsonView.as_view(schema),
        name='openapi_json',
    ),
    path(  # Requires the `django-modern-rest[openapi]` extra.
        'docs/openapi.yaml/',
        OpenAPIYamlView.as_view(schema),
        name='openapi_yaml',
    ),
    # Human-friendly documentation UIs backed by the same schema.
    path('docs/stoplight/', StoplightView.as_view(schema), name='stoplight'),
    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'),
]

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

Requirements for OpenAPI UIs

The HTML OpenAPI renderers (SwaggerView, RedocView, ScalarView, and StoplightView) depend on both Django templates and static files.

To use the bundled UI pages:

• Add 'dmr' to INSTALLED_APPS, so Django can discover the bundled renderer templates

• If you serve bundled assets locally, add 'django.contrib.staticfiles' to INSTALLED_APPS

• Configure Django templates so app templates can be discovered, for example by enabling APP_DIRS in the Django template backend

• Set STATIC_URL so Django can generate URLs for bundled static assets

In development, this is usually enough when using Django’s development server.

In production, make sure your static files setup is correct as described in the Django static files documentation and the staticfiles app reference.

If you switch renderers to CDN assets via dmr.settings.Settings.openapi_static_cdn, local static file serving is no longer required for those assets, but adding 'dmr' to the list of installed apps and template discovery are still required.

Note

By default, Swagger, Redoc, Stoplight, and Scalar use bundled static assets 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',
...     },
... }

Choosing a renderer and CSP

For the general Content-Security-Policy setup with Django, see Content Security Policy (CSP).

For OpenAPI specifically, the main thing to keep in mind is that final CSP compatibility still depends on the upstream renderer bundle you choose.

In general:

• SwaggerView is usually the best default when you want interactive docs with “try it out” support.

• RedocView is a good fit for mostly read-only, reference-style documentation.

• ScalarView and StoplightView are worth considering when you prefer their UI, but they tend to be more opinionated frontends with more moving parts.

Known caveats:

• If you switch to CDN assets, your CSP must allow those remote origins too.

• In practice, Swagger and Redoc are usually easier starting points than more feature-heavy frontend bundles.

Exporting the schema

Note

To use this feature, you must add 'dmr' to INSTALLED_APPS in your Django settings.

You can export the OpenAPI schema to stdout using the dmr_export_schema management command. This is useful for sharing the schema, committing it to version control, or automating client generation.

# Default JSON output:
python manage.py dmr_export_schema myapp.urls:schema

# Pretty-printed and sorted:
python manage.py dmr_export_schema myapp.urls:schema --indent 2 --sort-keys

# YAML output (requires 'django-modern-rest[openapi]' extra):
python manage.py dmr_export_schema myapp.urls:schema --format yaml --indent 2 --sort-keys

The positional argument is the import path to your OpenAPI instance, using a colon to separate the module from the attribute name (e.g. myapp.urls:schema).

Available options:

• --format — json (default) or yaml

• --indent — number of spaces, default: 2

• --sort-keys — sort keys alphabetically in the output

• --no-ensure-ascii — do not quote all non-ascii chars

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 router-level metadata

Router supports tags and deprecated parameters to apply OpenAPI metadata to all operations in the router:

urls.py

Show imports... 7 lines hidden

[source]

from django.urls import include

from dmr.openapi import build_schema
from dmr.openapi.views import OpenAPIJsonView
from dmr.routing import Router, path
from examples.getting_started.msgspec_controller import UserController

router = Router(
    'api/v1/users/',
    [
        path('', UserController.as_view()),
        path('<int:user_id>/', UserController.as_view()),
    ],
    tags=['users'],  # All endpoints tagged as 'users'
    deprecated=True,  # All endpoints are deprecated
)
schema = build_schema(router)

urlpatterns = [
    # Register our router in the final url patterns:
    path(router.prefix, include((router.urls, 'test_app'), namespace='api')),
    # Add swagger:
    path('docs/openapi.json/', OpenAPIJsonView.as_view(schema), name='openapi'),
]

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/v1/users/": {
      "post": {
        "deprecated": true,
        "operationId": "postUsercontrollerApiV1Users",
        "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"
          }
        },
        "tags": [
          "users"
        ]
      }
    },
    "/api/v1/users/{user_id}/": {
      "post": {
        "deprecated": true,
        "operationId": "postUsercontrollerApiV1UsersUserId",
        "parameters": [
          {
            "deprecated": false,
            "in": "path",
            "name": "user_id",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "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"
          }
        },
        "tags": [
          "users"
        ]
      }
    }
  }
}

• tags: List of strings to group operations in OpenAPI documentation

• deprecated: Boolean flag to mark all operations in this router as deprecated

These router-level settings are automatically merged with endpoint-level customizations set via @modify or @validate. Router tags are prepended to endpoint tags, and deprecated is set to True if either the router or endpoint has it enabled.

You can also set tags and deprecated at the individual endpoint level via @modify to override or extend router-level settings.

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: Literal['3.0.0', '3.1.0', '3.2.0'] = '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.

property openapi_version_info: tuple[int, int, int]

Returns the parsed OpenAPI version.

Added in version 0.8.0.

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.