Utilities to generate OpenAPI-compatible schema from API made with Django Rest Framework
Project description
DRF OpenAPI
Utilities to generate OpenAPI-compatible schema from API made with Django Rest Framework. Also use ReDoc as default interface.
Free software: MIT license
Documentation: https://drf-openapi.readthedocs.io.
Motivation
Django Rest Framework has an API schema generation/declaration mechanism provided by coreapi standard. There are a couple of problems with the current ecosystem:
CoreAPI is not compatible out of the box with OpenAPI which is a much more popular API standard with superior tooling support, i.e. Swagger et. al.
The OpenAPI codec (compatibility layer) that CoreAPI team provides drops / doesn’t support a number of useful OpenAPI features.
There is no support for versioning or method-specific schema.
This project was born to bridge the gap.
Usage
1. Quickstart
Out of the box, DRF OpenAPI inspects all of the endpoints reigstered with Django Rest Framework (DRF) and automatically generate documenation for them based on metadata provided by DRF and your serializer definitions. So no need to do anything, just plug it in:
# in settings.py
INSTALLED_APPS = [
...
'drf_openapi'
]
# in urls.py
urlpatterns += [url(f'{API_PREFIX}/', include('drf_openapi.urls'))]
And voila! Your API documentation will be available at <API_Prefix>/schema
2. Add schema to a view method
DRF OpenAPI support the separation of response schema and request schema on a per view method basis through the use of a view_config decorator
from drf_openapi.utils import view_config
class MeEndpointSet(viewsets.ViewSet):
@view_config(
request_serializer=MeRequestSerializer,
response_serializer=MeResponseSerializer,
validate_response=True)
def list(self, request, version) -> Response:
# the serializers are available on the self object
assert self.request_serializer == MeRequestSerializer
assert self.response_serializer == MeResponseSerializer
3. Add version to schema
DRF OpenAPI support schema versioning through versioning the serializers that the schema are generated from.
To make a serializer version-specific, extends VersionedSerializer
from drf_openapi.entities import VersionedSerializer
from rest_framework import serializers
class MeResponseSerializer(VersionedSerializer):
class V1(serializers.Serializer):
avatar = serializers.CharField(allowed_null=True)
class V2(serialiers.Serializer):
avatar = serializers.CharField(allowed_null=False)
VERSION_MAP = (
'>=1.0, <2.0': V1,
'>=2.0': V2
)
That’s it. The view_config
decorator will be able to correctly determined what serializer to use based on the request version at run time.
Features
1. Schema
Add per method schema definition through inspecting serializers
Add per serializer versioning
Add capability to generate response schema on an endpoint.
2. OpenAPI codec
Return response object as defined by the response schema
Return multiple response status codes and messages. [TODO]
3. UI
Support different OpenAPI UIs, not just Swagger. For example, ReDoc.
4. Utils
A declarative machanism to provide more metadata for an API endpoint and therefore providing richer information for documentation generation.
History
0.1.0 (2017-07-01)
First release on PyPI.
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_openapi-0.6.0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c5ee9a2dd78f012bc14a2e8a30c02e61c2feaec1b484ad631b5ad073ee60f36b |
|
MD5 | 715a0be4a59e10f5e61881a5bb0b6995 |
|
BLAKE2b-256 | bd93f9e9fb014bf5ab33626b6da9fa6dd7ce4b16cc5ce5d0ae1f86f2fa758a77 |