diff --git a/docs/api-guide/schemas.md b/docs/api-guide/schemas.md index 836ad4b6a3..4e05443e0c 100644 --- a/docs/api-guide/schemas.md +++ b/docs/api-guide/schemas.md @@ -572,10 +572,21 @@ Valid only if a `location="body"` field is included on the `Link`. A short description of the meaning and intended usage of the input field. +--- + +# Third party packages + +## DRF OpenAPI + +[DRF OpenAPI][drf-openapi] renders the schema generated by Django Rest Framework +in [OpenAPI][open-api] format. + + [cite]: https://blog.heroku.com/archives/2014/1/8/json_schema_for_heroku_platform_api [coreapi]: http://www.coreapi.org/ [corejson]: http://www.coreapi.org/specification/encoding/#core-json-encoding [open-api]: https://openapis.org/ +[drf-openapi]: https://github.com/limdauto/drf_openapi [json-hyperschema]: http://json-schema.org/latest/json-schema-hypermedia.html [api-blueprint]: https://apiblueprint.org/ [static-files]: https://docs.djangoproject.com/en/stable/howto/static-files/ diff --git a/docs/img/drf-openapi.png b/docs/img/drf-openapi.png new file mode 100644 index 0000000000..7a37e19d61 Binary files /dev/null and b/docs/img/drf-openapi.png differ diff --git a/docs/topics/documenting-your-api.md b/docs/topics/documenting-your-api.md index da1dbe358f..b68eb64ec2 100644 --- a/docs/topics/documenting-your-api.md +++ b/docs/topics/documenting-your-api.md @@ -75,6 +75,23 @@ When using viewsets, you should use the relevant action names as delimiters. There are a number of mature third-party packages for providing API documentation. +#### DRF OpenAPI + +[DRF OpenAPI][drf-openapi] bridges the gap between OpenAPI specification and tool chain with the schema exposed +out-of-the-box by Django Rest Framework. Its goals are: + + * To be dropped into any existing DRF project without any code change necessary. + * Provide clear disctinction between request schema and response schema. + * Provide a versioning mechanism for each schema. Support defining schema by version range syntax, e.g. >1.0, <=2.0 + * Support multiple response codes, not just 200 + * All this information should be bound to view methods, not view classes. + +It also tries to stay current with the maturing schema generation mechanism provided by DRF. + +![Screenshot - DRF OpenAPI][image-drf-openapi] + +--- + #### DRF Docs [DRF Docs][drfdocs-repo] allows you to document Web APIs made with Django REST Framework and it is authored by Emmanouil Konstantinidis. It's made to work out of the box and its setup should not take more than a couple of minutes. Complete documentation can be found on the [website][drfdocs-website] while there is also a [demo][drfdocs-demo] available for people to see what it looks like. **Live API Endpoints** allow you to utilize the endpoints from within the documentation in a neat way. @@ -197,6 +214,8 @@ In this approach, rather than documenting the available API endpoints up front, To implement a hypermedia API you'll need to decide on an appropriate media type for the API, and implement a custom renderer and parser for that media type. The [REST, Hypermedia & HATEOAS][hypermedia-docs] section of the documentation includes pointers to background reading, as well as links to various hypermedia formats. [cite]: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven +[drf-openapi]: https://github.com/limdauto/drf_openapi/ +[image-drf-openapi]: ../img/drf-openapi.png [drfdocs-repo]: https://github.com/ekonstantinidis/django-rest-framework-docs [drfdocs-website]: http://www.drfdocs.com/ [drfdocs-demo]: http://demo.drfdocs.com/ pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy