Metadata-Version: 2.1
Name: drf-yasg-json-api
Version: 0.3.0
Summary: Automated generation of real Swagger/OpenAPI 2.0 schemas for JSON API Django Rest Framework endpoints.
Home-page: https://github.com/glowka/drf-yasg-json-api
Author: 
Author-email: 
License: BSD License
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)
          - [Additional](#additional)
            - [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)
        
        <!-- END doctoc generated TOC please keep comment here to allow auto update -->
        
        
        ### 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](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',
            ],
        }
        ```
        
        Apply following changes:
        ```
        SWAGGER_SETTINGS = {
            'DEFAULT_AUTO_SCHEMA_CLASS': 'drf_yasg_json_api.view_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.IDFieldInspector',  # 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.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',
            ],
        }
        ```
        
        #### 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:
            - `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
            - `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.   
        
        #### 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 nested
         - `x-witeOonly` adds missing support for write only fields
        
        
        [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/
        
        
Keywords: drf django django-rest-framework schema swagger openapi codegen swagger-codegen documentation drf-yasg django-rest-swagger drf-openapi json-api
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Development Status :: 5 - Production/Stable
Classifier: Operating System :: OS Independent
Classifier: Environment :: Web Environment
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Framework :: Django
Classifier: Framework :: Django :: 1.11
Classifier: Framework :: Django :: 2.0
Classifier: Framework :: Django :: 2.1
Classifier: Framework :: Django :: 2.2
Classifier: Framework :: Django :: 3.0
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.6
Description-Content-Type: text/markdown
