Security News
Research
Data Theft Repackaged: A Case Study in Malicious Wrapper Packages on npm
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Automated generation of real Swagger/OpenAPI 2.0 schemas for JSON API Django Rest Framework endpoints.
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.
Django REST Framework JSON API: 2.8
, 3.0
, 3.1
, 3.2
, 4.0
, 4.1
, 4.2
, 4.3
, 5.0
Drf-yasg: 1.16
, 1.17.0
, 1.17.1
, 1.20
Django REST Framework: 3.8
, 3.9
, 3.10
, 3.11
, 3.12
, 3.13
Django: 2.0
, 2.1
, 2.2
, 3.0
, 3.1
, 3.2
, 4.0
Python: 3.6
, 3.7
, 3.8
, 3.9
pip install -U drf-yasg-json-api
First follow drf-yasg quickstart, then extend the configuration in following way.
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.JSONAPISerializerSmartInspector', # Added
'drf_yasg.inspectors.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',
],
}
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!
Fields and query params extraction follows Django REST framework JSON API.
data
field with id
, type
, relationships
, attributes
structureSchema based on view's main serializer. It accessed through view's get_serializer
method,
the same way drf-yasg
does it.
Use GenericAPIView
or APIView
and define get_serializer
manually.
Fields and their source:
id
– id
field or other serializer field that matches the model pk
field or in-the-fly generated serializer field for model pk
type
– serializer's model JSON API resource name or view's resource name,
the same way Django REST framework JSON API does itrelationships
– all serializer fields of RelatedField
and ManyRelatedField
classattributes
– all other serializer fieldsincluded
field and include
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 of filter[]
query param will be generated based on view's filterset_fields
attribute.
If view uses JsonApiPageNumberPagination
or JsonApiLimitOffsetPagination
as pagination_class
,
schema of links
and meta
, consistent with those pagination types, will be generated.
swagger_auto_schema
decorator of drf-yasg
JSON API schema is also generated for success responses (statuses 2XX) defined manually using responses
argument
of swagger_auto_schema
decorator.
write_only
fields from response and read_only
from requestdrf_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
x-writeOnly
and x-readOnly
propertiesdrf_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 fieldsJSON API docs will be generated by drf_yasg_json_api.inspectors.JSONAPISerializerInspector
,
non JSON API views are ignored by this inspector.
Pure REST API docs will be generated by drf-yasg
inspectors – either
drf_yasg.inspectors.ReferencingSerializerInspector
or drf_yasg.inspectors.InlineSerializerInspector
depending on
which one you prefer to use.
RecursiveField follows different approach from JSON API, so it cannot be used with
JSONAPISerializerInspector
, but you can still have pure REST API views that will be documented
using ReferencingSerializerInspector
.
Alternatively, instead of RecursiveField
you can use included_serializers
with self
(e.g. included_serializers = {'related-obj': 'self'}
) to implement limited in depth recursion
the JSON API way.
FAQs
Automated generation of real Swagger/OpenAPI 2.0 schemas for JSON API Django Rest Framework endpoints.
We found that drf-yasg-json-api demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.