Automated generation of real Swagger/OpenAPI 2.0 schemas for JSON API Django Rest Framework endpoints.
Project description
drf-yasg-json-api - drf-yasg meets JSON API
Automated generation of Swagger/OpenAPI 2.0 JSON API specifications from Django Rest Framework endpoints.
This package makes drf-yasg Yet Another Swagger Generator and Django REST framework JSON API play together.
Table of Contents
Compatibility
-
Django REST Framework JSON API:
2.4
,2.5
,2.6
,2.7
,2.8
,3.0
,3.1
-
Drf-yasg:
1.4
,1.5
,1.6
,1.7.0
,1.7.1
-
Django REST Framework:
3.7
,3.8
,3.9
,3.10
,3.11
-
Django:
2.0
,2.1
,2.2
,3.0
-
Python:
3.5
,3.6
,3.7
,3.8
Installation
pip install -U drf_yasg_json_api
Quickstart
First follow drf-yasg quickstart, then extend the configuration in following way.
Extending drg-yasg configuration
Assuming you are using drf-yasg configuration like below (which is drf-yasg default):
SWAGGER_SETTINGS = {
'DEFAULT_AUTO_SCHEMA_CLASS': 'drf_yasg.inspectors.SwaggerAutoSchema',
'DEFAULT_FIELD_INSPECTORS': [
'drf_yasg.inspectors.CamelCaseJSONFilter',
'drf_yasg.inspectors.RecursiveFieldInspector',
'drf_yasg.inspectors.ReferencingSerializerInspector',
'drf_yasg.inspectors.ChoiceFieldInspector',
'drf_yasg.inspectors.FileFieldInspector',
'drf_yasg.inspectors.DictFieldInspector',
'drf_yasg.inspectors.JSONFieldInspector',
'drf_yasg.inspectors.HiddenFieldInspector',
'drf_yasg.inspectors.RelatedFieldInspector',
'drf_yasg.inspectors.SerializerMethodFieldInspector',
'drf_yasg.inspectors.SimpleFieldInspector',
'drf_yasg.inspectors.StringDefaultFieldInspector',
],
'DEFAULT_FILTER_INSPECTORS': [
'drf_yasg.inspectors.CoreAPICompatInspector',
],
'DEFAULT_PAGINATOR_INSPECTORS': [
'drf_yasg.inspectors.DjangoRestResponsePagination',
'drf_yasg.inspectors.CoreAPICompatInspector',
],
}
Apply following changes:
SWAGGER_SETTINGS = {
'DEFAULT_AUTO_SCHEMA_CLASS': 'drf_yasg_json_api.inspectors.SwaggerAutoSchema', # Overridden
'DEFAULT_FIELD_INSPECTORS': [
'drf_yasg_json_api.inspectors.NamesFormatFilter', # Replaces CamelCaseJSONFilter
'drf_yasg.inspectors.RecursiveFieldInspector',
'drf_yasg_json_api.inspectors.XPropertiesFilter', # Added
'drf_yasg_json_api.inspectors.InlineSerializerSmartInspector', # Replaces ReferencingSerializerInspector
'drf_yasg_json_api.inspectors.IntegerIDFieldInspector', # Added
'drf_yasg.inspectors.ChoiceFieldInspector',
'drf_yasg.inspectors.FileFieldInspector',
'drf_yasg.inspectors.DictFieldInspector',
'drf_yasg.inspectors.JSONFieldInspector',
'drf_yasg.inspectors.HiddenFieldInspector',
'drf_yasg_json_api.inspectors.ManyRelatedFieldInspector', # Added
'drf_yasg_json_api.inspectors.IntegerPrimaryKeyRelatedFieldInspector', # Added
'drf_yasg.inspectors.RelatedFieldInspector',
'drf_yasg.inspectors.SerializerMethodFieldInspector',
'drf_yasg.inspectors.SimpleFieldInspector',
'drf_yasg.inspectors.StringDefaultFieldInspector',
],
'DEFAULT_FILTER_INSPECTORS': [
'drf_yasg_json_api.inspectors.DjangoFilterInspector', # Added (optional), requires django_filter
'drf_yasg.inspectors.CoreAPICompatInspector',
],
'DEFAULT_PAGINATOR_INSPECTORS': [
'drf_yasg_json_api.inspectors.DjangoRestResponsePagination', # Added
'drf_yasg.inspectors.DjangoRestResponsePagination',
'drf_yasg.inspectors.CoreAPICompatInspector',
],
}
Renderers and parsers
JSON API schema of your view's response or request will be generated if you use django-rest-framework-json-api
's
JSONAPIRenderer
or JSONAPIParser
respectively.
But since you have already used them to render or parse, not just to generate schema (haven't you?), you probably only need to alter the configuration as described above.
That's it!
Features
Fields and query params extraction follows Django REST framework JSON API.
Main request/response JSON API schema support:
-
data
field withid
,type
,relationships
,attributes
structureSchema based on view's main serializer:
id
–id
field or other serializer field that matches the modelpk
field or in-the-fly generated serializer field for modelpk
type
– serializer's model JSON API resource namerelationships
– all serializer fields ofRelatedField
andManyRelatedField
classattributes
– all other serializer fields
-
included
field andinclude
query paramSchema based on serializers defined in
included_serializer
attribute of view's main serializer where each one is treated in the same way as view's main serializer (data
field). -
filter
query paramIf view uses
django_filters.DjangoFilterBackend
as filter backend, schema offilter[]
query param will be generated based on view'sfilterset_fields
attribute. -
pagination
If view uses
JsonApiPageNumberPagination
orJsonApiLimitOffsetPagination
aspagination_class
, schema oflinks
andmeta
, consistent with those pagination types, will be generated.
Additional
Stripping write_only
fields from response and read_only
from request
drf_yasg_json_api.inspectors.InlineSerializerSmartInspector
strips fields inaccessible in request/response to
provide view of fields that are really available to use.
You can revert to traditional drf-yasg
view of all serializer fields in both response and request by replacing this
inspector with drf_yasg_json_api.inspectors.InlineSerializerInspector
Extra x-writeOnly
and x-readOnly
properties
drf_yasg_json_api.inspectors.XPropertiesFilter
uses:
x-readOnly
to mark read only fields even if they are nestedx-witeOonly
adds missing support for write only fields
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for drf_yasg_json_api-0.7.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ea684d42be019c1e6cd8fb83a8826eff11990aade189d1b5ecebf5555ab982f1 |
|
MD5 | f6cbeb4e13139623742635cb16db1ecc |
|
BLAKE2b-256 | 16c53846bdc64eac3868e23d2cd080cd1e47d8e83944254d57d5a5b95684c39c |