2020-06-02 12:07:44 +03:00
<!DOCTYPE html>
< html lang = "en" >
< head >
< meta http-equiv = "Content-Type" content = "text/html; charset=UTF-8" >
< meta charset = "utf-8" >
< title > Schemas - Django REST framework< / title >
< link href = "../../img/favicon.ico" rel = "icon" type = "image/x-icon" >
< link rel = "canonical" href = "https://www.django-rest-framework.org/api-guide/schemas/" / >
< meta name = "viewport" content = "width=device-width, initial-scale=1.0" >
< meta name = "description" content = "Django, API, REST, Schemas" >
< meta name = "author" content = "Tom Christie" >
<!-- Le styles -->
< link href = "../../css/prettify.css" rel = "stylesheet" >
< link href = "../../css/bootstrap.css" rel = "stylesheet" >
< link href = "../../css/bootstrap-responsive.css" rel = "stylesheet" >
< link href = "../../css/default.css" rel = "stylesheet" >
< script type = "text/javascript" >
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-18852272-2']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script');
ga.type = 'text/javascript';
ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(ga, s);
})();
< / script >
< style >
#sidebarInclude img {
margin-bottom: 10px;
}
#sidebarInclude a.promo {
color: black;
}
@media (max-width: 767px) {
div.promo {
display: none;
}
}
< / style >
< / head >
< body onload = "prettyPrint()" class = "-page" >
< div class = "wrapper" >
< div class = "navbar navbar-inverse navbar-fixed-top" >
< div class = "navbar-inner" >
< div class = "container-fluid" >
< a class = "repo-link btn btn-primary btn-small" href = "https://github.com/encode/django-rest-framework/tree/master" > GitHub< / a >
< a class = "repo-link btn btn-inverse btn-small " rel = "next" href = "../format-suffixes/" >
Next < i class = "icon-arrow-right icon-white" > < / i >
< / a >
< a class = "repo-link btn btn-inverse btn-small " rel = "prev" href = "../metadata/" >
< i class = "icon-arrow-left icon-white" > < / i > Previous
< / a >
< a id = "search_modal_show" class = "repo-link btn btn-inverse btn-small" href = "#mkdocs_search_modal" data-toggle = "modal" data-target = "#mkdocs_search_modal" > < i class = "icon-search icon-white" > < / i > Search< / a >
< a class = "btn btn-navbar" data-toggle = "collapse" data-target = ".nav-collapse" >
< span class = "icon-bar" > < / span >
< span class = "icon-bar" > < / span >
< span class = "icon-bar" > < / span >
< / a >
< a class = "brand" href = "https://www.django-rest-framework.org/" > Django REST framework< / a >
< div class = "nav-collapse collapse" >
<!-- Main navigation -->
< ul class = "nav navbar-nav" >
< li >
< a href = "../.." > Home< / a >
< / li >
< li class = "dropdown" >
< a href = "#" class = "dropdown-toggle" data-toggle = "dropdown" > Tutorial < b class = "caret" > < / b > < / a >
< ul class = "dropdown-menu" >
< li >
< a href = "../../tutorial/quickstart/" > Quickstart< / a >
< / li >
< li >
< a href = "../../tutorial/1-serialization/" > 1 - Serialization< / a >
< / li >
< li >
< a href = "../../tutorial/2-requests-and-responses/" > 2 - Requests and responses< / a >
< / li >
< li >
< a href = "../../tutorial/3-class-based-views/" > 3 - Class based views< / a >
< / li >
< li >
< a href = "../../tutorial/4-authentication-and-permissions/" > 4 - Authentication and permissions< / a >
< / li >
< li >
< a href = "../../tutorial/5-relationships-and-hyperlinked-apis/" > 5 - Relationships and hyperlinked APIs< / a >
< / li >
< li >
< a href = "../../tutorial/6-viewsets-and-routers/" > 6 - Viewsets and routers< / a >
< / li >
< / ul >
< / li >
< li class = "dropdown active" >
< a href = "#" class = "dropdown-toggle" data-toggle = "dropdown" > API Guide < b class = "caret" > < / b > < / a >
< ul class = "dropdown-menu" >
< li >
< a href = "../requests/" > Requests< / a >
< / li >
< li >
< a href = "../responses/" > Responses< / a >
< / li >
< li >
< a href = "../views/" > Views< / a >
< / li >
< li >
< a href = "../generic-views/" > Generic views< / a >
< / li >
< li >
< a href = "../viewsets/" > Viewsets< / a >
< / li >
< li >
< a href = "../routers/" > Routers< / a >
< / li >
< li >
< a href = "../parsers/" > Parsers< / a >
< / li >
< li >
< a href = "../renderers/" > Renderers< / a >
< / li >
< li >
< a href = "../serializers/" > Serializers< / a >
< / li >
< li >
< a href = "../fields/" > Serializer fields< / a >
< / li >
< li >
< a href = "../relations/" > Serializer relations< / a >
< / li >
< li >
< a href = "../validators/" > Validators< / a >
< / li >
< li >
< a href = "../authentication/" > Authentication< / a >
< / li >
< li >
< a href = "../permissions/" > Permissions< / a >
< / li >
< li >
< a href = "../caching/" > Caching< / a >
< / li >
< li >
< a href = "../throttling/" > Throttling< / a >
< / li >
< li >
< a href = "../filtering/" > Filtering< / a >
< / li >
< li >
< a href = "../pagination/" > Pagination< / a >
< / li >
< li >
< a href = "../versioning/" > Versioning< / a >
< / li >
< li >
< a href = "../content-negotiation/" > Content negotiation< / a >
< / li >
< li >
< a href = "../metadata/" > Metadata< / a >
< / li >
< li class = "active" >
< a href = "./" > Schemas< / a >
< / li >
< li >
< a href = "../format-suffixes/" > Format suffixes< / a >
< / li >
< li >
< a href = "../reverse/" > Returning URLs< / a >
< / li >
< li >
< a href = "../exceptions/" > Exceptions< / a >
< / li >
< li >
< a href = "../status-codes/" > Status codes< / a >
< / li >
< li >
< a href = "../testing/" > Testing< / a >
< / li >
< li >
< a href = "../settings/" > Settings< / a >
< / li >
< / ul >
< / li >
< li class = "dropdown" >
< a href = "#" class = "dropdown-toggle" data-toggle = "dropdown" > Topics < b class = "caret" > < / b > < / a >
< ul class = "dropdown-menu" >
< li >
< a href = "../../topics/documenting-your-api/" > Documenting your API< / a >
< / li >
< li >
< a href = "../../topics/api-clients/" > API Clients< / a >
< / li >
< li >
< a href = "../../topics/internationalization/" > Internationalization< / a >
< / li >
< li >
< a href = "../../topics/ajax-csrf-cors/" > AJAX, CSRF & CORS< / a >
< / li >
< li >
< a href = "../../topics/html-and-forms/" > HTML & Forms< / a >
< / li >
< li >
< a href = "../../topics/browser-enhancements/" > Browser Enhancements< / a >
< / li >
< li >
< a href = "../../topics/browsable-api/" > The Browsable API< / a >
< / li >
< li >
< a href = "../../topics/rest-hypermedia-hateoas/" > REST, Hypermedia & HATEOAS< / a >
< / li >
< / ul >
< / li >
< li class = "dropdown" >
< a href = "#" class = "dropdown-toggle" data-toggle = "dropdown" > Community < b class = "caret" > < / b > < / a >
< ul class = "dropdown-menu" >
< li >
< a href = "../../community/tutorials-and-resources/" > Tutorials and Resources< / a >
< / li >
< li >
< a href = "../../community/third-party-packages/" > Third Party Packages< / a >
< / li >
< li >
< a href = "../../community/contributing/" > Contributing to REST framework< / a >
< / li >
< li >
< a href = "../../community/project-management/" > Project management< / a >
< / li >
< li >
< a href = "../../community/release-notes/" > Release Notes< / a >
< / li >
2022-09-22 14:39:11 +03:00
< li >
< a href = "../../community/3.14-announcement/" > 3.14 Announcement< / a >
< / li >
2021-12-13 16:11:32 +03:00
< li >
< a href = "../../community/3.13-announcement/" > 3.13 Announcement< / a >
< / li >
2020-09-28 12:55:30 +03:00
< li >
< a href = "../../community/3.12-announcement/" > 3.12 Announcement< / a >
< / li >
2020-06-02 12:07:44 +03:00
< li >
< a href = "../../community/3.11-announcement/" > 3.11 Announcement< / a >
< / li >
< li >
< a href = "../../community/3.10-announcement/" > 3.10 Announcement< / a >
< / li >
< li >
< a href = "../../community/3.9-announcement/" > 3.9 Announcement< / a >
< / li >
< li >
< a href = "../../community/3.8-announcement/" > 3.8 Announcement< / a >
< / li >
< li >
< a href = "../../community/3.7-announcement/" > 3.7 Announcement< / a >
< / li >
< li >
< a href = "../../community/3.6-announcement/" > 3.6 Announcement< / a >
< / li >
< li >
< a href = "../../community/3.5-announcement/" > 3.5 Announcement< / a >
< / li >
< li >
< a href = "../../community/3.4-announcement/" > 3.4 Announcement< / a >
< / li >
< li >
< a href = "../../community/3.3-announcement/" > 3.3 Announcement< / a >
< / li >
< li >
< a href = "../../community/3.2-announcement/" > 3.2 Announcement< / a >
< / li >
< li >
< a href = "../../community/3.1-announcement/" > 3.1 Announcement< / a >
< / li >
< li >
< a href = "../../community/3.0-announcement/" > 3.0 Announcement< / a >
< / li >
< li >
< a href = "../../community/kickstarter-announcement/" > Kickstarter Announcement< / a >
< / li >
< li >
< a href = "../../community/mozilla-grant/" > Mozilla Grant< / a >
< / li >
< li >
< a href = "../../community/funding/" > Funding< / a >
< / li >
< li >
< a href = "../../community/jobs/" > Jobs< / a >
< / li >
< / ul >
< / li >
< / ul >
< / div >
<!-- /.nav - collapse -->
< / div >
< / div >
< / div >
< div class = "body-content" >
< div class = "container-fluid" >
<!-- Search Modal -->
< div id = "mkdocs_search_modal" class = "modal hide fade" tabindex = "-1" role = "dialog" aria-labelledby = "myModalLabel" aria-hidden = "true" >
< div class = "modal-header" >
< button type = "button" class = "close" data-dismiss = "modal" aria-hidden = "true" > × < / button >
< h3 id = "myModalLabel" > Documentation search< / h3 >
< / div >
< div class = "modal-body" >
< form role = "form" autocomplete = "off" >
< div class = "form-group" >
< input type = "text" name = "q" class = "form-control" placeholder = "Search..." id = "mkdocs-search-query" >
< / div >
< / form >
< div id = "mkdocs-search-results" > < / div >
< / div >
< div class = "modal-footer" >
< button class = "btn" data-dismiss = "modal" aria-hidden = "true" > Close< / button >
< / div >
< / div >
< div class = "row-fluid" >
< div class = "span3" >
< div id = "table-of-contents" >
< ul class = "nav nav-list side-nav well sidebar-nav-fixed" >
< li class = "main" >
< a href = "#schema" > Schema< / a >
< / li >
2020-09-28 12:55:30 +03:00
< li >
< a href = "#overview" > Overview< / a >
< / li >
2020-06-02 12:07:44 +03:00
< li >
< a href = "#generating-an-openapi-schema" > Generating an OpenAPI Schema< / a >
< / li >
< li >
2020-09-28 12:55:30 +03:00
< a href = "#schemagenerator" > SchemaGenerator< / a >
< / li >
< li >
< a href = "#autoschema" > AutoSchema< / a >
2020-06-02 12:07:44 +03:00
< / li >
< div class = "promo" >
< hr / >
< div id = "sidebarInclude" >
< / div >
< / ul >
< / div >
< / div >
< div id = "main-content" class = "span9" >
< a class = "github" href = "https://github.com/encode/django-rest-framework/tree/master/rest_framework/schemas" >
< span class = "label label-info" > schemas< / span >
< / a >
< h1 id = "schema" > < a class = "toclink" href = "#schema" > Schema< / a > < / h1 >
< blockquote >
< p > A machine-readable [schema] describes what resources are available via the API, what their URLs are, how they are represented and what operations they support.< / p >
2021-09-10 16:45:21 +03:00
< p > — Heroku, < a href = "https://blog.heroku.com/archives/2014/1/8/json_schema_for_heroku_platform_api" > JSON Schema for the Heroku Platform API< / a > < / p >
2020-06-02 12:07:44 +03:00
< / blockquote >
< p > API schemas are a useful tool that allow for a range of use cases, including
generating reference documentation, or driving dynamic client libraries that
can interact with your API.< / p >
< p > Django REST Framework provides support for automatic generation of
< a href = "https://github.com/OAI/OpenAPI-Specification" > OpenAPI< / a > schemas.< / p >
2020-09-28 12:55:30 +03:00
< h2 id = "overview" > < a class = "toclink" href = "#overview" > Overview< / a > < / h2 >
< p > Schema generation has several moving parts. It's worth having an overview:< / p >
< ul >
< li > < code > SchemaGenerator< / code > is a top-level class that is responsible for walking your
configured URL patterns, finding < code > APIView< / code > subclasses, enquiring for their
schema representation, and compiling the final schema object.< / li >
< li > < code > AutoSchema< / code > encapsulates all the details necessary for per-view schema
introspection. Is attached to each view via the < code > schema< / code > attribute. You
subclass < code > AutoSchema< / code > in order to customize your schema.< / li >
< li > The < code > generateschema< / code > management command allows you to generate a static schema
offline.< / li >
< li > Alternatively, you can route < code > SchemaView< / code > to dynamically generate and serve
your schema.< / li >
< li > < code > settings.DEFAULT_SCHEMA_CLASS< / code > allows you to specify an < code > AutoSchema< / code >
subclass to serve as your project's default.< / li >
< / ul >
< p > The following sections explain more.< / p >
2020-06-02 12:07:44 +03:00
< h2 id = "generating-an-openapi-schema" > < a class = "toclink" href = "#generating-an-openapi-schema" > Generating an OpenAPI Schema< / a > < / h2 >
2020-07-29 16:56:27 +03:00
< h3 id = "install-dependencies" > < a class = "toclink" href = "#install-dependencies" > Install dependencies< / a > < / h3 >
< pre > < code > pip install pyyaml uritemplate
2020-06-02 12:07:44 +03:00
< / code > < / pre >
2020-07-29 16:56:27 +03:00
< ul >
< li > < code > pyyaml< / code > is used to generate schema into YAML-based OpenAPI format.< / li >
< li > < code > uritemplate< / code > is used internally to get parameters in path.< / li >
< / ul >
2020-06-02 12:07:44 +03:00
< h3 id = "generating-a-static-schema-with-the-generateschema-management-command" > < a class = "toclink" href = "#generating-a-static-schema-with-the-generateschema-management-command" > Generating a static schema with the < code > generateschema< / code > management command< / a > < / h3 >
< p > If your schema is static, you can use the < code > generateschema< / code > management command:< / p >
2020-11-06 01:19:01 +03:00
< pre > < code class = "language-bash" > ./manage.py generateschema --file openapi-schema.yml
2020-06-02 12:07:44 +03:00
< / code > < / pre >
< p > Once you've generated a schema in this way you can annotate it with any
additional information that cannot be automatically inferred by the schema
generator.< / p >
< p > You might want to check your API schema into version control and update it
with each new release, or serve the API schema from your site's static media.< / p >
< h3 id = "generating-a-dynamic-schema-with-schemaview" > < a class = "toclink" href = "#generating-a-dynamic-schema-with-schemaview" > Generating a dynamic schema with < code > SchemaView< / code > < / a > < / h3 >
< p > If you require a dynamic schema, because foreign key choices depend on database
values, for example, you can route a < code > SchemaView< / code > that will generate and serve
your schema on demand.< / p >
< p > To route a < code > SchemaView< / code > , use the < code > get_schema_view()< / code > helper.< / p >
< p > In < code > urls.py< / code > :< / p >
2020-11-06 01:19:01 +03:00
< pre > < code class = "language-python" > from rest_framework.schemas import get_schema_view
2020-06-02 12:07:44 +03:00
urlpatterns = [
# ...
# Use the `get_schema_view()` helper to add a `SchemaView` to project URLs.
# * `title` and `description` parameters are passed to `SchemaGenerator`.
# * Provide view name for use with `reverse()`.
path('openapi', get_schema_view(
title=" Your Project" ,
description=" API for all things …" ,
version=" 1.0.0"
), name='openapi-schema'),
# ...
]
< / code > < / pre >
< h4 id = "get_schema_view" > < a class = "toclink" href = "#get_schema_view" > < code > get_schema_view()< / code > < / a > < / h4 >
< p > The < code > get_schema_view()< / code > helper takes the following keyword arguments:< / p >
< ul >
< li > < code > title< / code > : May be used to provide a descriptive title for the schema definition.< / li >
< li > < code > description< / code > : Longer descriptive text.< / li >
< li > < code > version< / code > : The version of the API.< / li >
< li >
< p > < code > url< / code > : May be used to pass a canonical base URL for the schema.< / p >
< pre > < code > schema_view = get_schema_view(
title='Server Monitoring API',
url='https://www.example.org/api/'
)
< / code > < / pre >
< / li >
< li >
< p > < code > urlconf< / code > : A string representing the import path to the URL conf that you want
to generate an API schema for. This defaults to the value of Django's
< code > ROOT_URLCONF< / code > setting.< / p >
< pre > < code > schema_view = get_schema_view(
title='Server Monitoring API',
url='https://www.example.org/api/',
urlconf='myproject.urls'
)
< / code > < / pre >
< / li >
< li >
< p > < code > patterns< / code > : List of url patterns to limit the schema introspection to. If you
only want the < code > myproject.api< / code > urls to be exposed in the schema:< / p >
< pre > < code > schema_url_patterns = [
2020-09-28 12:55:30 +03:00
path('api/', include('myproject.api.urls')),
2020-06-02 12:07:44 +03:00
]
schema_view = get_schema_view(
title='Server Monitoring API',
url='https://www.example.org/api/',
patterns=schema_url_patterns,
)
< / code > < / pre >
< / li >
< li >
< p > < code > generator_class< / code > : May be used to specify a < code > SchemaGenerator< / code > subclass to be
passed to the < code > SchemaView< / code > .< / p >
< / li >
< li > < code > authentication_classes< / code > : May be used to specify the list of authentication
classes that will apply to the schema endpoint. Defaults to
< code > settings.DEFAULT_AUTHENTICATION_CLASSES< / code > < / li >
< li > < code > permission_classes< / code > : May be used to specify the list of permission classes
that will apply to the schema endpoint. Defaults to
< code > settings.DEFAULT_PERMISSION_CLASSES< / code > .< / li >
< li > < code > renderer_classes< / code > : May be used to pass the set of renderer classes that can
be used to render the API root endpoint.< / li >
< / ul >
2020-09-28 12:55:30 +03:00
< h2 id = "schemagenerator" > < a class = "toclink" href = "#schemagenerator" > SchemaGenerator< / a > < / h2 >
< p > < strong > Schema-level customization< / strong > < / p >
2020-11-06 01:19:01 +03:00
< pre > < code class = "language-python" > from rest_framework.schemas.openapi import SchemaGenerator
2020-09-28 12:55:30 +03:00
< / code > < / pre >
< p > < code > SchemaGenerator< / code > is a class that walks a list of routed URL patterns, requests
the schema for each view and collates the resulting OpenAPI schema.< / p >
< p > Typically you won't need to instantiate < code > SchemaGenerator< / code > yourself, but you can
do so like so:< / p >
2020-06-02 12:07:44 +03:00
< pre > < code > generator = SchemaGenerator(title='Stock Prices API')
< / code > < / pre >
< p > Arguments:< / p >
< ul >
< li > < code > title< / code > < strong > required< / strong > : The name of the API.< / li >
< li > < code > description< / code > : Longer descriptive text.< / li >
< li > < code > version< / code > : The version of the API. Defaults to < code > 0.1.0< / code > .< / li >
< li > < code > url< / code > : The root URL of the API schema. This option is not required unless the schema is included under path prefix.< / li >
< li > < code > patterns< / code > : A list of URLs to inspect when generating the schema. Defaults to the project's URL conf.< / li >
< li > < code > urlconf< / code > : A URL conf module name to use when generating the schema. Defaults to < code > settings.ROOT_URLCONF< / code > .< / li >
< / ul >
2020-09-28 12:55:30 +03:00
< p > In order to customize the top-level schema, subclass
< code > rest_framework.schemas.openapi.SchemaGenerator< / code > and provide your subclass
as an argument to the < code > generateschema< / code > command or < code > get_schema_view()< / code > helper
function.< / p >
2022-09-22 14:39:11 +03:00
< h3 id = "get_schemaself-requestnone-publicfalse" > < a class = "toclink" href = "#get_schemaself-requestnone-publicfalse" > get_schema(self, request=None, public=False)< / a > < / h3 >
2020-06-02 12:07:44 +03:00
< p > Returns a dictionary that represents the OpenAPI schema:< / p >
< pre > < code > generator = SchemaGenerator(title='Stock Prices API')
schema = generator.get_schema()
< / code > < / pre >
< p > The < code > request< / code > argument is optional, and may be used if you want to apply
per-user permissions to the resulting schema generation.< / p >
< p > This is a good point to override if you want to customize the generated
2020-09-28 12:55:30 +03:00
dictionary For example you might wish to add terms of service to the < a href = "https://swagger.io/specification/#infoObject" > top-level
< code > info< / code > object< / a > :< / p >
< pre > < code > class TOSSchemaGenerator(SchemaGenerator):
2020-11-06 01:19:01 +03:00
def get_schema(self, *args, **kwargs):
schema = super().get_schema(*args, **kwargs)
2020-09-28 12:55:30 +03:00
schema[" info" ][" termsOfService" ] = " https://example.com/tos.html"
return schema
2020-06-02 12:07:44 +03:00
< / code > < / pre >
2020-09-28 12:55:30 +03:00
< h2 id = "autoschema" > < a class = "toclink" href = "#autoschema" > AutoSchema< / a > < / h2 >
< p > < strong > Per-View Customization< / strong > < / p >
2020-11-06 01:19:01 +03:00
< pre > < code class = "language-python" > from rest_framework.schemas.openapi import AutoSchema
2020-09-28 12:55:30 +03:00
< / code > < / pre >
< p > By default, view introspection is performed by an < code > AutoSchema< / code > instance
accessible via the < code > schema< / code > attribute on < code > APIView< / code > .< / p >
< pre > < code > auto_schema = some_view.schema
2020-06-02 12:07:44 +03:00
< / code > < / pre >
2020-09-28 12:55:30 +03:00
< p > < code > AutoSchema< / code > provides the OpenAPI elements needed for each view, request method
and path:< / p >
< ul >
< li > A list of < a href = "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#componentsObject" > OpenAPI components< / a > . In DRF terms these are
mappings of serializers that describe request and response bodies.< / li >
< li > The appropriate < a href = "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#operationObject" > OpenAPI operation object< / a > that describes
the endpoint, including path and query parameters for pagination, filtering,
and so on.< / li >
< / ul >
2020-11-06 01:19:01 +03:00
< pre > < code class = "language-python" > components = auto_schema.get_components(...)
2020-09-28 12:55:30 +03:00
operation = auto_schema.get_operation(...)
2020-06-02 12:07:44 +03:00
< / code > < / pre >
2020-09-28 12:55:30 +03:00
< p > In compiling the schema, < code > SchemaGenerator< / code > calls < code > get_components()< / code > and
< code > get_operation()< / code > for each view, allowed method, and path.< / p >
2020-07-29 16:56:27 +03:00
< hr / >
2020-09-28 12:55:30 +03:00
< p > < strong > Note< / strong > : The automatic introspection of components, and many operation
parameters relies on the relevant attributes and methods of
< code > GenericAPIView< / code > : < code > get_serializer()< / code > , < code > pagination_class< / code > , < code > filter_backends< / code > ,
etc. For basic < code > APIView< / code > subclasses, default introspection is essentially limited to
the URL kwarg path parameters for this reason.< / p >
2020-07-29 16:56:27 +03:00
< hr / >
2020-09-28 12:55:30 +03:00
< p > < code > AutoSchema< / code > encapsulates the view introspection needed for schema generation.
Because of this all the schema generation logic is kept in a single place,
rather than being spread around the already extensive view, serializer and
field APIs.< / p >
< p > Keeping with this pattern, try not to let schema logic leak into your own
views, serializers, or fields when customizing the schema generation. You might
be tempted to do something like this:< / p >
2020-11-06 01:19:01 +03:00
< pre > < code class = "language-python" > class CustomSchema(AutoSchema):
2020-09-28 12:55:30 +03:00
" " "
AutoSchema subclass using schema_extra_info on the view.
" " "
2020-07-29 16:56:27 +03:00
...
2020-09-28 12:55:30 +03:00
class CustomView(APIView):
schema = CustomSchema()
schema_extra_info = ... some extra info ...
< / code > < / pre >
< p > Here, the < code > AutoSchema< / code > subclass goes looking for < code > schema_extra_info< / code > on the
view. This is < em > OK< / em > (it doesn't actually hurt) but it means you'll end up with
your schema logic spread out in a number of different places.< / p >
< p > Instead try to subclass < code > AutoSchema< / code > such that the < code > extra_info< / code > doesn't leak
out into the view:< / p >
2020-11-06 01:19:01 +03:00
< pre > < code class = "language-python" > class BaseSchema(AutoSchema):
2020-09-28 12:55:30 +03:00
" " "
AutoSchema subclass that knows how to use extra_info.
" " "
2020-07-29 16:56:27 +03:00
...
2020-09-28 12:55:30 +03:00
class CustomSchema(BaseSchema):
extra_info = ... some extra info ...
2020-07-29 16:56:27 +03:00
2020-09-28 12:55:30 +03:00
class CustomView(APIView):
schema = CustomSchema()
2020-07-29 16:56:27 +03:00
< / code > < / pre >
2020-09-28 12:55:30 +03:00
< p > This style is slightly more verbose but maintains the encapsulation of the
schema related code. It's more < em > cohesive< / em > in the < em > parlance< / em > . It'll keep the
rest of your API code more tidy.< / p >
< p > If an option applies to many view classes, rather than creating a specific
subclass per-view, you may find it more convenient to allow specifying the
option as an < code > __init__()< / code > kwarg to your base < code > AutoSchema< / code > subclass:< / p >
2020-11-06 01:19:01 +03:00
< pre > < code class = "language-python" > class CustomSchema(BaseSchema):
2020-09-28 12:55:30 +03:00
def __init__(self, **kwargs):
# store extra_info for later
self.extra_info = kwargs.pop(" extra_info" )
super().__init__(**kwargs)
2020-07-29 16:56:27 +03:00
2020-09-28 12:55:30 +03:00
class CustomView(APIView):
schema = CustomSchema(
extra_info=... some extra info ...
)
2020-07-29 16:56:27 +03:00
< / code > < / pre >
2020-09-28 12:55:30 +03:00
< p > This saves you having to create a custom subclass per-view for a commonly used option.< / p >
< p > Not all < code > AutoSchema< / code > methods expose related < code > __init__()< / code > kwargs, but those for
the more commonly needed options do.< / p >
< h3 id = "autoschema-methods" > < a class = "toclink" href = "#autoschema-methods" > < code > AutoSchema< / code > methods< / a > < / h3 >
< h4 id = "get_components" > < a class = "toclink" href = "#get_components" > < code > get_components()< / code > < / a > < / h4 >
< p > Generates the OpenAPI components that describe request and response bodies,
deriving their properties from the serializer.< / p >
< p > Returns a dictionary mapping the component name to the generated
representation. By default this has just a single pair but you may override
< code > get_components()< / code > to return multiple pairs if your view uses multiple
serializers.< / p >
< h4 id = "get_component_name" > < a class = "toclink" href = "#get_component_name" > < code > get_component_name()< / code > < / a > < / h4 >
< p > Computes the component's name from the serializer.< / p >
< p > You may see warnings if your API has duplicate component names. If so you can override < code > get_component_name()< / code > or pass the < code > component_name< / code > < code > __init__()< / code > kwarg (see below) to provide different names.< / p >
2022-09-22 14:39:11 +03:00
< h4 id = "get_reference" > < a class = "toclink" href = "#get_reference" > < code > get_reference()< / code > < / a > < / h4 >
< p > Returns a reference to the serializer component. This may be useful if you override < code > get_schema()< / code > .< / p >
2020-09-28 12:55:30 +03:00
< h4 id = "map_serializer" > < a class = "toclink" href = "#map_serializer" > < code > map_serializer()< / code > < / a > < / h4 >
< p > Maps serializers to their OpenAPI representations.< / p >
< p > Most serializers should conform to the standard OpenAPI < code > object< / code > type, but you may
wish to override < code > map_serializer()< / code > in order to customize this or other
serializer-level fields.< / p >
< h4 id = "map_field" > < a class = "toclink" href = "#map_field" > < code > map_field()< / code > < / a > < / h4 >
< p > Maps individual serializer fields to their schema representation. The base implementation
will handle the default fields that Django REST Framework provides.< / p >
< p > For < code > SerializerMethodField< / code > instances, for which the schema is unknown, or custom field subclasses you should override < code > map_field()< / code > to generate the correct schema:< / p >
2020-11-06 01:19:01 +03:00
< pre > < code class = "language-python" > class CustomSchema(AutoSchema):
2020-09-28 12:55:30 +03:00
" " " Extension of ``AutoSchema`` to add support for custom field schemas." " "
2020-07-29 16:56:27 +03:00
2020-09-28 12:55:30 +03:00
def map_field(self, field):
# Handle SerializerMethodFields or custom fields here...
# ...
return super().map_field(field)
2020-07-29 16:56:27 +03:00
< / code > < / pre >
2020-09-28 12:55:30 +03:00
< p > Authors of third-party packages should aim to provide an < code > AutoSchema< / code > subclass,
and a mixin, overriding < code > map_field()< / code > so that users can easily generate schemas
for their custom fields.< / p >
< h4 id = "get_tags" > < a class = "toclink" href = "#get_tags" > < code > get_tags()< / code > < / a > < / h4 >
< p > OpenAPI groups operations by tags. By default tags taken from the first path
segment of the routed URL. For example, a URL like < code > /users/{id}/< / code > will generate
the tag < code > users< / code > .< / p >
< p > You can pass an < code > __init__()< / code > kwarg to manually specify tags (see below), or
override < code > get_tags()< / code > to provide custom logic.< / p >
< h4 id = "get_operation" > < a class = "toclink" href = "#get_operation" > < code > get_operation()< / code > < / a > < / h4 >
< p > Returns the < a href = "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#operationObject" > OpenAPI operation object< / a > that describes the
endpoint, including path and query parameters for pagination, filtering, and so
on.< / p >
< p > Together with < code > get_components()< / code > , this is the main entry point to the view
introspection.< / p >
< h4 id = "get_operation_id" > < a class = "toclink" href = "#get_operation_id" > < code > get_operation_id()< / code > < / a > < / h4 >
< p > There must be a unique < a href = "openapi-operationid" > operationid< / a > for each operation.
By default the < code > operationId< / code > is deduced from the model name, serializer name or
view name. The operationId looks like "listItems", "retrieveItem",
"updateItem", etc. The < code > operationId< / code > is camelCase by convention.< / p >
< h4 id = "get_operation_id_base" > < a class = "toclink" href = "#get_operation_id_base" > < code > get_operation_id_base()< / code > < / a > < / h4 >
< p > If you have several views with the same model name, you may see duplicate
operationIds.< / p >
< p > In order to work around this, you can override < code > get_operation_id_base()< / code > to
provide a different base for name part of the ID.< / p >
2021-09-10 16:45:21 +03:00
< h4 id = "get_serializer" > < a class = "toclink" href = "#get_serializer" > < code > get_serializer()< / code > < / a > < / h4 >
< p > If the view has implemented < code > get_serializer()< / code > , returns the result.< / p >
< h4 id = "get_request_serializer" > < a class = "toclink" href = "#get_request_serializer" > < code > get_request_serializer()< / code > < / a > < / h4 >
< p > By default returns < code > get_serializer()< / code > but can be overridden to
differentiate between request and response objects.< / p >
< h4 id = "get_response_serializer" > < a class = "toclink" href = "#get_response_serializer" > < code > get_response_serializer()< / code > < / a > < / h4 >
< p > By default returns < code > get_serializer()< / code > but can be overridden to
differentiate between request and response objects.< / p >
2020-09-28 12:55:30 +03:00
< h3 id = "autoschema__init__-kwargs" > < a class = "toclink" href = "#autoschema__init__-kwargs" > < code > AutoSchema.__init__()< / code > kwargs< / a > < / h3 >
< p > < code > AutoSchema< / code > provides a number of < code > __init__()< / code > kwargs that can be used for
common customizations, if the default generated values are not appropriate.< / p >
< p > The available kwargs are:< / p >
2020-07-29 16:56:27 +03:00
< ul >
2020-09-28 12:55:30 +03:00
< li > < code > tags< / code > : Specify a list of tags.< / li >
< li > < code > component_name< / code > : Specify the component name.< / li >
< li > < code > operation_id_base< / code > : Specify the resource-name part of operation IDs.< / li >
2020-07-29 16:56:27 +03:00
< / ul >
2020-09-28 12:55:30 +03:00
< p > You pass the kwargs when declaring the < code > AutoSchema< / code > instance on your view:< / p >
< pre > < code > class PetDetailView(generics.RetrieveUpdateDestroyAPIView):
schema = AutoSchema(
tags=['Pets'],
component_name='Pet',
operation_id_base='Pet',
)
...
2020-07-29 16:56:27 +03:00
< / code > < / pre >
2020-09-28 12:55:30 +03:00
< p > Assuming a < code > Pet< / code > model and < code > PetSerializer< / code > serializer, the kwargs in this
example are probably not needed. Often, though, you'll need to pass the kwargs
if you have multiple view targeting the same model, or have multiple views with
identically named serializers.< / p >
< p > If your views have related customizations that are needed frequently, you can
create a base < code > AutoSchema< / code > subclass for your project that takes additional
< code > __init__()< / code > kwargs to save subclassing < code > AutoSchema< / code > for each view.< / p >
2020-06-02 12:07:44 +03:00
< / div > <!-- /span -->
< / div > <!-- /row -->
< / div > <!-- /.fluid - container -->
< / div > <!-- /.body content -->
< div id = "push" > < / div >
< / div > <!-- /.wrapper -->
< footer class = "span12" >
< p > Documentation built with < a href = "http://www.mkdocs.org/" > MkDocs< / a > .
< / p >
< / footer >
<!-- Le javascript
================================================== -->
<!-- Placed at the end of the document so the pages load faster -->
< script async src = "https://fund.django-rest-framework.org/sidebar_include.js" > < / script >
< script src = "../../js/jquery-1.8.1-min.js" > < / script >
< script src = "../../js/prettify-1.0.js" > < / script >
< script src = "../../js/bootstrap-2.1.1-min.js" > < / script >
< script src = "../../js/theme.js" > < / script >
< script > var base _url = '../..' ; < / script >
< script src = "../../search/main.js" defer > < / script >
< script >
var shiftWindow = function() {
scrollBy(0, -50)
};
if (location.hash) shiftWindow();
window.addEventListener("hashchange", shiftWindow);
$('.dropdown-menu').on('click touchstart', function(event) {
event.stopPropagation();
});
// Dynamically force sidenav/dropdown to no higher than browser window
$('.side-nav, .dropdown-menu').css('max-height', window.innerHeight - 130);
$(function() {
$(window).resize(function() {
$('.side-nav, .dropdown-menu').css('max-height', window.innerHeight - 130);
});
});
< / script >
< / body >
< / html >
