diff options
Diffstat (limited to 'python-drf-yasg-json-api.spec')
| -rw-r--r-- | python-drf-yasg-json-api.spec | 743 |
1 files changed, 743 insertions, 0 deletions
diff --git a/python-drf-yasg-json-api.spec b/python-drf-yasg-json-api.spec new file mode 100644 index 0000000..060f5c3 --- /dev/null +++ b/python-drf-yasg-json-api.spec @@ -0,0 +1,743 @@ +%global _empty_manifest_terminate_build 0 +Name: python-drf-yasg-json-api +Version: 0.9.1 +Release: 1 +Summary: Automated generation of real Swagger/OpenAPI 2.0 schemas for JSON API Django Rest Framework endpoints. +License: BSD License +URL: https://github.com/glowka/drf-yasg-json-api +Source0: https://mirrors.nju.edu.cn/pypi/web/packages/94/61/47d77b088335fe509fad381edd1e839cd7afd052b075a760230c4d3fc917/drf-yasg-json-api-0.9.1.tar.gz +BuildArch: noarch + +Requires: python3-django +Requires: python3-djangorestframework +Requires: python3-djangorestframework-jsonapi +Requires: python3-django-filter +Requires: python3-drf-yasg + +%description +## drf-yasg-json-api - ***drf-yasg*** meets ***JSON API*** + +[![build-status-image]][travis] +[![coverage-status-image]][codecov] +[![pypi-version]][pypi] + +Automated generation of Swagger/OpenAPI 2.0 ***JSON API*** specifications from Django Rest Framework endpoints. + +This package makes [drf-yasg Yet Another Swagger Generator](https://github.com/axnsan12/drf-yasg) and +[Django REST framework JSON API](https://github.com/django-json-api/django-rest-framework-json-api) play together. + +#### Table of Contents +<!-- START doctoc generated TOC please keep comment here to allow auto update --> +<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> + + +- [Compatibility](#compatibility) +- [Installation](#installation) +- [Quickstart](#quickstart) + - [Extending drg-yasg configuration](#extending-drg-yasg-configuration) + - [Renderers and parsers](#renderers-and-parsers) +- [Features](#features) + - [Main request/response JSON API schema support:](#main-requestresponse-json-api-schema-support) + - [`data` field with `id`, `type`, `relationships`, `attributes` structure](#data-field-with-id-type-relationships-attributes-structure) + - [`included` field and `include` query param](#included-field-and-include-query-param) + - [`filter` query param](#filter-query-param) + - [pagination](#pagination) + - [Additional](#additional) + - [Support for `swagger_auto_schema` decorator of `drf-yasg`](#support-for-swagger_auto_schema-decorator-of-drf-yasg) + - [Stripping `write_only` fields from response and `read_only` from request](#stripping-write_only-fields-from-response-and-read_only-from-request) + - [Extra `x-writeOnly` and `x-readOnly` properties](#extra-x-writeonly-and-x-readonly-properties) +- [Coexistence of JSON API views with pure REST API views](#coexistence-of-json-api-views-with-pure-rest-api-views) + +<!-- END doctoc generated TOC please keep comment here to allow auto update --> + + +### Compatibility + +- 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` + +### Installation + +``` +pip install -U drf-yasg-json-api +``` + +### Quickstart + +First follow [drf-yasg quickstart](https://github.com/axnsan12/drf-yasg#1-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.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', + ], +} +``` + +#### 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 with `id`, `type`, `relationships`, `attributes` structure + + Schema 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 it* + - `relationships` – all serializer fields of `RelatedField` and `ManyRelatedField` class + - `attributes` – all other serializer fields + +- ##### `included` field and `include` query param + + Schema 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 param + + If view uses `django_filters.DjangoFilterBackend` as filter backend, + schema of `filter[]` query param will be generated based on view's `filterset_fields` attribute. + +- ##### pagination + + If view uses `JsonApiPageNumberPagination` or `JsonApiLimitOffsetPagination` as `pagination_class`, + schema of `links` and `meta`, consistent with those pagination types, will be generated. + +#### Additional + +##### Support for `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. + +##### 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 nested + - `x-witeOonly` adds missing support for write only fields + +### Coexistence of JSON API views with pure REST API views + +JSON 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 + +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`](https://github.com/django-json-api/django-rest-framework-json-api/blob/9c49b65894a38a185b34737f569785d720eccc67/docs/usage.md#included) +with `self` (e.g. `included_serializers = {'related-obj': 'self'}`) to implement limited in depth recursion +the JSON API way. + + +[build-status-image]: https://secure.travis-ci.org/glowka/drf-yasg-json-api.svg?branch=master +[travis]: https://travis-ci.org/glowka/drf-yasg-json-api?branch=master +[coverage-status-image]: https://img.shields.io/codecov/c/github/glowka/drf-yasg-json-api/master.svg +[codecov]: https://codecov.io/github/glowka/drf-yasg-json-api?branch=master +[pypi-version]: https://img.shields.io/pypi/v/drf_yasg_json_api.svg +[pypi]: https://pypi.org/project/drf_yasg_json_api/ + + + + + +%package -n python3-drf-yasg-json-api +Summary: Automated generation of real Swagger/OpenAPI 2.0 schemas for JSON API Django Rest Framework endpoints. +Provides: python-drf-yasg-json-api +BuildRequires: python3-devel +BuildRequires: python3-setuptools +BuildRequires: python3-pip +%description -n python3-drf-yasg-json-api +## drf-yasg-json-api - ***drf-yasg*** meets ***JSON API*** + +[![build-status-image]][travis] +[![coverage-status-image]][codecov] +[![pypi-version]][pypi] + +Automated generation of Swagger/OpenAPI 2.0 ***JSON API*** specifications from Django Rest Framework endpoints. + +This package makes [drf-yasg Yet Another Swagger Generator](https://github.com/axnsan12/drf-yasg) and +[Django REST framework JSON API](https://github.com/django-json-api/django-rest-framework-json-api) play together. + +#### Table of Contents +<!-- START doctoc generated TOC please keep comment here to allow auto update --> +<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> + + +- [Compatibility](#compatibility) +- [Installation](#installation) +- [Quickstart](#quickstart) + - [Extending drg-yasg configuration](#extending-drg-yasg-configuration) + - [Renderers and parsers](#renderers-and-parsers) +- [Features](#features) + - [Main request/response JSON API schema support:](#main-requestresponse-json-api-schema-support) + - [`data` field with `id`, `type`, `relationships`, `attributes` structure](#data-field-with-id-type-relationships-attributes-structure) + - [`included` field and `include` query param](#included-field-and-include-query-param) + - [`filter` query param](#filter-query-param) + - [pagination](#pagination) + - [Additional](#additional) + - [Support for `swagger_auto_schema` decorator of `drf-yasg`](#support-for-swagger_auto_schema-decorator-of-drf-yasg) + - [Stripping `write_only` fields from response and `read_only` from request](#stripping-write_only-fields-from-response-and-read_only-from-request) + - [Extra `x-writeOnly` and `x-readOnly` properties](#extra-x-writeonly-and-x-readonly-properties) +- [Coexistence of JSON API views with pure REST API views](#coexistence-of-json-api-views-with-pure-rest-api-views) + +<!-- END doctoc generated TOC please keep comment here to allow auto update --> + + +### Compatibility + +- 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` + +### Installation + +``` +pip install -U drf-yasg-json-api +``` + +### Quickstart + +First follow [drf-yasg quickstart](https://github.com/axnsan12/drf-yasg#1-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.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', + ], +} +``` + +#### 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 with `id`, `type`, `relationships`, `attributes` structure + + Schema 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 it* + - `relationships` – all serializer fields of `RelatedField` and `ManyRelatedField` class + - `attributes` – all other serializer fields + +- ##### `included` field and `include` query param + + Schema 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 param + + If view uses `django_filters.DjangoFilterBackend` as filter backend, + schema of `filter[]` query param will be generated based on view's `filterset_fields` attribute. + +- ##### pagination + + If view uses `JsonApiPageNumberPagination` or `JsonApiLimitOffsetPagination` as `pagination_class`, + schema of `links` and `meta`, consistent with those pagination types, will be generated. + +#### Additional + +##### Support for `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. + +##### 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 nested + - `x-witeOonly` adds missing support for write only fields + +### Coexistence of JSON API views with pure REST API views + +JSON 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 + +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`](https://github.com/django-json-api/django-rest-framework-json-api/blob/9c49b65894a38a185b34737f569785d720eccc67/docs/usage.md#included) +with `self` (e.g. `included_serializers = {'related-obj': 'self'}`) to implement limited in depth recursion +the JSON API way. + + +[build-status-image]: https://secure.travis-ci.org/glowka/drf-yasg-json-api.svg?branch=master +[travis]: https://travis-ci.org/glowka/drf-yasg-json-api?branch=master +[coverage-status-image]: https://img.shields.io/codecov/c/github/glowka/drf-yasg-json-api/master.svg +[codecov]: https://codecov.io/github/glowka/drf-yasg-json-api?branch=master +[pypi-version]: https://img.shields.io/pypi/v/drf_yasg_json_api.svg +[pypi]: https://pypi.org/project/drf_yasg_json_api/ + + + + + +%package help +Summary: Development documents and examples for drf-yasg-json-api +Provides: python3-drf-yasg-json-api-doc +%description help +## drf-yasg-json-api - ***drf-yasg*** meets ***JSON API*** + +[![build-status-image]][travis] +[![coverage-status-image]][codecov] +[![pypi-version]][pypi] + +Automated generation of Swagger/OpenAPI 2.0 ***JSON API*** specifications from Django Rest Framework endpoints. + +This package makes [drf-yasg Yet Another Swagger Generator](https://github.com/axnsan12/drf-yasg) and +[Django REST framework JSON API](https://github.com/django-json-api/django-rest-framework-json-api) play together. + +#### Table of Contents +<!-- START doctoc generated TOC please keep comment here to allow auto update --> +<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> + + +- [Compatibility](#compatibility) +- [Installation](#installation) +- [Quickstart](#quickstart) + - [Extending drg-yasg configuration](#extending-drg-yasg-configuration) + - [Renderers and parsers](#renderers-and-parsers) +- [Features](#features) + - [Main request/response JSON API schema support:](#main-requestresponse-json-api-schema-support) + - [`data` field with `id`, `type`, `relationships`, `attributes` structure](#data-field-with-id-type-relationships-attributes-structure) + - [`included` field and `include` query param](#included-field-and-include-query-param) + - [`filter` query param](#filter-query-param) + - [pagination](#pagination) + - [Additional](#additional) + - [Support for `swagger_auto_schema` decorator of `drf-yasg`](#support-for-swagger_auto_schema-decorator-of-drf-yasg) + - [Stripping `write_only` fields from response and `read_only` from request](#stripping-write_only-fields-from-response-and-read_only-from-request) + - [Extra `x-writeOnly` and `x-readOnly` properties](#extra-x-writeonly-and-x-readonly-properties) +- [Coexistence of JSON API views with pure REST API views](#coexistence-of-json-api-views-with-pure-rest-api-views) + +<!-- END doctoc generated TOC please keep comment here to allow auto update --> + + +### Compatibility + +- 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` + +### Installation + +``` +pip install -U drf-yasg-json-api +``` + +### Quickstart + +First follow [drf-yasg quickstart](https://github.com/axnsan12/drf-yasg#1-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.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', + ], +} +``` + +#### 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 with `id`, `type`, `relationships`, `attributes` structure + + Schema 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 it* + - `relationships` – all serializer fields of `RelatedField` and `ManyRelatedField` class + - `attributes` – all other serializer fields + +- ##### `included` field and `include` query param + + Schema 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 param + + If view uses `django_filters.DjangoFilterBackend` as filter backend, + schema of `filter[]` query param will be generated based on view's `filterset_fields` attribute. + +- ##### pagination + + If view uses `JsonApiPageNumberPagination` or `JsonApiLimitOffsetPagination` as `pagination_class`, + schema of `links` and `meta`, consistent with those pagination types, will be generated. + +#### Additional + +##### Support for `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. + +##### 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 nested + - `x-witeOonly` adds missing support for write only fields + +### Coexistence of JSON API views with pure REST API views + +JSON 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 + +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`](https://github.com/django-json-api/django-rest-framework-json-api/blob/9c49b65894a38a185b34737f569785d720eccc67/docs/usage.md#included) +with `self` (e.g. `included_serializers = {'related-obj': 'self'}`) to implement limited in depth recursion +the JSON API way. + + +[build-status-image]: https://secure.travis-ci.org/glowka/drf-yasg-json-api.svg?branch=master +[travis]: https://travis-ci.org/glowka/drf-yasg-json-api?branch=master +[coverage-status-image]: https://img.shields.io/codecov/c/github/glowka/drf-yasg-json-api/master.svg +[codecov]: https://codecov.io/github/glowka/drf-yasg-json-api?branch=master +[pypi-version]: https://img.shields.io/pypi/v/drf_yasg_json_api.svg +[pypi]: https://pypi.org/project/drf_yasg_json_api/ + + + + + +%prep +%autosetup -n drf-yasg-json-api-0.9.1 + +%build +%py3_build + +%install +%py3_install +install -d -m755 %{buildroot}/%{_pkgdocdir} +if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi +if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi +if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi +if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi +pushd %{buildroot} +if [ -d usr/lib ]; then + find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/lib64 ]; then + find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/bin ]; then + find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/sbin ]; then + find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst +fi +touch doclist.lst +if [ -d usr/share/man ]; then + find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst +fi +popd +mv %{buildroot}/filelist.lst . +mv %{buildroot}/doclist.lst . + +%files -n python3-drf-yasg-json-api -f filelist.lst +%dir %{python3_sitelib}/* + +%files help -f doclist.lst +%{_docdir}/* + +%changelog +* Thu May 18 2023 Python_Bot <Python_Bot@openeuler.org> - 0.9.1-1 +- Package Spec generated |