From d7d795abf14cfa2ca0d699e500f9dce0777ee65d Mon Sep 17 00:00:00 2001
From: "T. Franzel" <13507857+tfranzel@users.noreply.github.com>
Date: Thu, 17 Sep 2020 11:59:02 +0200
Subject: [PATCH] Add third-party schema library drf-spectacular to docs

---
 docs/coreapi/schemas.md             |  7 +++++++
 docs/topics/documenting-your-api.md | 11 +++++++++++
 2 files changed, 18 insertions(+)

diff --git a/docs/coreapi/schemas.md b/docs/coreapi/schemas.md
index e7a418b80..653105a7a 100644
--- a/docs/coreapi/schemas.md
+++ b/docs/coreapi/schemas.md
@@ -828,10 +828,17 @@ A short description of the meaning and intended usage of the input field.
 [drf-yasg][drf-yasg] generates [OpenAPI][open-api] documents suitable for code generation - nested schemas,
 named models, response bodies, enum/pattern/min/max validators, form parameters, etc.
 
+
+## drf-spectacular - Sane and flexible OpenAPI 3.0 schema generation for Django REST framework
+
+[drf-spectacular][drf-spectacular] is a [OpenAPI 3][open-api] schema generation tool with explicit focus on extensibility,
+customizability and client generation. It's usage patterns are very similar to [drf-yasg][drf-yasg].
+
 [cite]: https://blog.heroku.com/archives/2014/1/8/json_schema_for_heroku_platform_api
 [coreapi]: https://www.coreapi.org/
 [corejson]: https://www.coreapi.org/specification/encoding/#core-json-encoding
 [drf-yasg]: https://github.com/axnsan12/drf-yasg/
+[drf-spectacular]: https://github.com/tfranzel/drf-spectacular/
 [open-api]: https://openapis.org/
 [json-hyperschema]: https://json-schema.org/latest/json-schema-hypermedia.html
 [api-blueprint]: https://apiblueprint.org/
diff --git a/docs/topics/documenting-your-api.md b/docs/topics/documenting-your-api.md
index 5c5872650..7f39a9c33 100644
--- a/docs/topics/documenting-your-api.md
+++ b/docs/topics/documenting-your-api.md
@@ -142,6 +142,16 @@ This also translates into a very useful interactive documentation viewer in the
 
 ![Screenshot - drf-yasg][image-drf-yasg]
 
+#### drf-spectacular - Sane and flexible OpenAPI 3.0 schema generation for Django REST framework
+
+[drf-spectacular][drf-spectacular] is a [OpenAPI 3][open-api] schema generation tool with explicit focus on extensibility,
+customizability and client generation. Usage patterns are very similar to [drf-yasg][drf-yasg].
+
+It aims to extract as much schema information as possible, while providing decorators and extensions for easy
+customization. There is explicit support for [swagger-codegen][swagger], [SwaggerUI][swagger-ui] and [Redoc][redoc],
+i18n, versioning, authentication, polymorphism (dynamic requests and responses), query/path/header parameters,
+documentation and more. Several popular plugins for DRF are supported out-of-the-box as well.
+
 ---
 
 ## Self describing APIs
@@ -216,6 +226,7 @@ To implement a hypermedia API you'll need to decide on an appropriate media type
 [image-self-describing-api]: ../img/self-describing.png
 
 [drf-yasg]: https://github.com/axnsan12/drf-yasg/
+[drf-spectacular]: https://github.com/tfranzel/drf-spectacular/
 [markdown]: https://daringfireball.net/projects/markdown/syntax
 [open-api]: https://openapis.org/
 [redoc]: https://github.com/Rebilly/ReDoc