From f9871b800a6d2c141e2636c8beb93d7cc41c848b Mon Sep 17 00:00:00 2001 From: Pavlin Gergov Date: Sun, 22 Mar 2020 20:09:05 +0200 Subject: [PATCH] Add section about documentation --- README.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) diff --git a/README.md b/README.md index b9a2107..d5ba84c 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,12 @@ Expect often updates as we discuss & decide upon different things. + [Tasks](#tasks) * [Periodic Tasks](#periodic-tasks) * [Configuration](#configuration-1) +- [Documentation](#documentation) + * [The OpenAPI Specification](#the-openapi-specification) + * [Generate automated documentation](#generate-automated-documentation) + + [drf-yasg](#drf-yasg) + + [Django REST Framework](#django-rest-framework) + * [Rendering the documentation](#rendering-the-documentation) - [Inspiration](#inspiration) @@ -1254,6 +1260,80 @@ Celery is a complex topic, so it's a good idea to invest time reading the docume We constantly do that & find new things or find better approaches to our problems. +## Documentation + +Before we begin, we'll clarify that `Swagger` and `OpenAPI` are two completely different things. + +* OpenAPI is a specification that defines a standard, programming language-agnostic interface description for REST APIs. +* Swagger is one of the many tools for implementing the OpenAPI specification. + +### The OpenAPI Specification + +There are two major versions of the OpenAPI specification (OAS): + +1. [OpenAPI 2](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) - formerly known as the Swagger Specification. It was renamed after SmartBear Software donated the specification to the OpenAPI Initiative. You can read more about that [here](https://www.openapis.org/faq). +2. [OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md) - the first official release of the specification by the [OpenAPI Initiative](https://www.openapis.org). If you're interested to see what's new check [this article](https://swagger.io/blog/news/whats-new-in-openapi-3-0/). + +The latest version can be found [here](https://github.com/OAI/OpenAPI-Specification). + +### Generate automated documentation + +You can manually write the `.yml` or `.json` schema of your project. This approach allows the usage of all features available in the specification version of your choice. Flexibility comes at a price and we find it very difficult and time-consuming to keep the schema up to date. + +With automated schema generation, you don't have to worry about keeping it up to date, but some of the specification's features may not be supported. + +#### drf-yasg + +[drf-yasg](https://github.com/axnsan12/drf-yasg) is an opensource Django package. It's compatible with: + +* Django 1.11 and above +* DRF 3.8 and above +* Python 2.7, 3.6 and above + +*Keep in mind Django 1.11 is the last version that supports Python 2.7.* + +It generates an `OpenAPI 2` compatible schema. There aren't any signs that support for `OpenAPI 3` will be added. + +So far we've managed to cover all of our needs using the package. Here're a couple of use cases: + +* Multiple authentications +* Versioning +* Query parameters +* Request and response bodies +* Pagination +* Examples +* Models +* Deprecation + +In case you need anything else, check the official documentation [here](https://drf-yasg.readthedocs.io/en/stable/). + +There're a lot of configurable settings [here](https://drf-yasg.readthedocs.io/en/stable/settings.html). + +#### Django Rest Framework + +Version `3.9` of Django REST Framework came with [Built-in OpenAPI schema support](https://www.django-rest-framework.org/community/3.9-announcement/#built-in-openapi-schema-support). It's compatible with: + +* Django 1.11 and above +* DRF 3.9 and above +* Python 2.7, 3.6, and above + +The generated schema supports the new `OpenAPI 3.0` specification. So far only a couple of features are supported: + +* Request or response body (but not both) +* Query parameters +* Pagination +* Examples + +If you need more than that - you'll need to write it by yourself. + +If DRF evolves enough and supports all, or most of, drf-yasg's features we would love to migrate to it. Until then `drf-yasg` is our tool of choice. + +### Rendering the documentation + +How you visualize a project's API documentation is a matter of choice. We've used both [Swagger UI](https://github.com/swagger-api/swagger-ui) and [ReDoc](https://github.com/Redocly/redoc) with a great success. + +You can find more OpenAPI tools [here](https://openapi.tools). + ## Inspiration The way we do Django is inspired by the following things: