encode/django-rest-framework
1
1
Fork 0
mirror of https://github.com/encode/django-rest-framework.git synced 2025-08-04 12:30:11 +03:00
Code Issues Packages Projects Releases Wiki Activity

Adjust API Reference docs

Browse Source
This commit is contained in:
Carlton Gibson 2017-08-29 10:21:37 +02:00
parent dc92b55c84
commit 7aa52aca71
1 changed files with 33 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
docs/api-guide/schemas.md
View File

@ -372,8 +372,8 @@ to the Open API ("Swagger") format:
## SchemaGenerator ## SchemaGenerator
A class that deals with introspecting your API views, which can be used to A class that walks a list of routed URL patterns, requests the schema for each view,
generate a schema. and collates the resulting CoreAPI Document.
Typically you'll instantiate `SchemaGenerator` with a single argument, like so: Typically you'll instantiate `SchemaGenerator` with a single argument, like so:
@ -406,36 +406,60 @@ Return a nested dictionary containing all the links that should be included in t
This is a good point to override if you want to modify the resulting structure of the generated schema, This is a good point to override if you want to modify the resulting structure of the generated schema,
as you can build a new dictionary with a different layout. as you can build a new dictionary with a different layout.
### get_link(self, path, method, view)
## APIViewSchemaDescriptor
A class that deals with introspection of individual views for schema generation.
`APIViewSchemaDescriptor` is attached to `APIView` via the `schema` attribute.
Typically you will subclass `APIViewSchemaDescriptor` to customise schema generation
and then set your subclass on your view.
class CustomViewSchema(APIViewSchemaDescriptor):
"""
Overrides `get_link()` to provide Custom Behavior X
"""
def get_link(self, path, method, base_url):
link = super().get_link(path, method, base_url)
# Do something to customize link here...
return link
class MyView(APIView):
schema = CustomViewSchema()
### get_link(self, path, method, base_url)
Returns a `coreapi.Link` instance corresponding to the given view. Returns a `coreapi.Link` instance corresponding to the given view.
You can override this if you need to provide custom behaviors for particular views. You can override this if you need to provide custom behaviors for particular views.
### get_description(self, path, method, view) ### get_description(self, path, method)
Returns a string to use as the link description. By default this is based on the Returns a string to use as the link description. By default this is based on the
view docstring as described in the "Schemas as Documentation" section above. view docstring as described in the "Schemas as Documentation" section above.
### get_encoding(self, path, method, view) ### get_encoding(self, path, method)
Returns a string to indicate the encoding for any request body, when interacting Returns a string to indicate the encoding for any request body, when interacting
with the given view. Eg. `'application/json'`. May return a blank string for views with the given view. Eg. `'application/json'`. May return a blank string for views
that do not expect a request body. that do not expect a request body.
### get_path_fields(self, path, method, view): ### get_path_fields(self, path, method):
Return a list of `coreapi.Link()` instances. One for each path parameter in the URL. Return a list of `coreapi.Link()` instances. One for each path parameter in the URL.
### get_serializer_fields(self, path, method, view) ### get_serializer_fields(self, path, method)
Return a list of `coreapi.Link()` instances. One for each field in the serializer class used by the view. Return a list of `coreapi.Link()` instances. One for each field in the serializer class used by the view.
### get_pagination_fields(self, path, method, view ### get_pagination_fields(self, path, method)
Return a list of `coreapi.Link()` instances, as returned by the `get_schema_fields()` method on any pagination class used by the view. Return a list of `coreapi.Link()` instances, as returned by the `get_schema_fields()` method on any pagination class used by the view.
### get_filter_fields(self, path, method, view) ### get_filter_fields(self, path, method)
Return a list of `coreapi.Link()` instances, as returned by the `get_schema_fields()` method of any filter classes used by the view. Return a list of `coreapi.Link()` instances, as returned by the `get_schema_fields()` method of any filter classes used by the view.