前言
持续创作，加速成长！这是我参与「掘金日新计划 · 6 月更文挑战」的第 18 天，点击查看活动详情
现在我们已经完成了 API，我们需要一种向其他人快速准确地记录其功能的方法。 毕竟，在大多数公司和团队中，使用该API的开发人员与最初构建该API的开发人员不同。 幸运的是，有自动化工具可以为我们解决这个问题。
模式是机器可读的文档，概述了它们支持的所有可用 API 端点，URL 和 HTTP 谓词（ GET，POST，PUT，DELETE 等）。 文档是添加到架构中的东西，它使人类更易于阅读和使用。 在本文中，我们将向我们的 Blog 项目添加一个架构，然后添加两种不同的文档生成方法。 到最后，我们将实现一种自动化的方式来记录对当前 API 状态和将来的任何更改。
提醒一下，这是我们当前 API 端点的完整列表：
模式
从3.9版开始，Django REST Framework引入了对OpenAPI模式（以前称为 Swagger ）的内置支持。 最终将取代使用Core API生成架构的当前方法。
但是，由于这是一个迭代过渡，因此我们将在项目中使用传统的 Core API 方法自动生成 API 模式。 核心 API 与格式无关，这意味着它可以用于各种文档中。 基本上，您通常会首先使用 Core API 来生成模式，然后确定要在其中使用哪种文档格式。
我们还需要安装 pyyaml，这将使我们以常用的基于 YAML 的 OpenAPI 格式呈现架构。
首先安装两个软件包。 确保本地服务器未运行 Control + c。
(blogapi) $ pipenv install coreapi==2.3.3 pyyaml==5.1.2
Django REST Framework 内置了对 Core API的支持，因此我们只需要将其添加到项目级别的 blog_project/urls.py 文件中即可。 无需高级配置。
代码如下：
# blog_project/urls.py
from django.contrib import admin
from django.urls import include, path
from rest_framework.schemas import get_schema_view # new
schema_view = get_schema_view(title='Blog API') # new
urlpatterns = [
path('admin/', admin.site.urls),
path('api/v1/', include('posts.urls')),
path('api-auth/', include('rest_framework.urls')),
path('api/v1/rest-auth/', include('rest_auth.urls')),
path('api/v1/rest-auth/registration/',
include('rest_auth.registration.urls')),
path('schema/', schema_view), # new
]
我们首先导入get_schema_view，为其命名为 Blog API ，然后为 schema/ 添加URL路由。
如果您再次使用 python manage.py runserver 启动本地服务器，并导航至位于 http://127.0.0.1:8000/schema/ 的新架构URL端点，我们将看到可以使用整个API的自动生成的架构。
文档
由于模式是为机器而非人类设计的，因此可以阅读 Django REST 框架，并且还具有内置的 API 文档功能，该功能可将模式转换为对其他开发人员更友好的格式。
要包括默认的 API 文档，我们需要在 urls.py 文件中添加两行。 首先，导入 include_docs_urls，然后为 docs/ 添加新路由。
# blog_project/urls.py
from django.contrib import admin
from django.urls import include, path
from rest_framework.documentation import include_docs_urls # new from rest_framework.schemas import get_schema_view
schema_view = get_schema_view(title='Blog API')
urlpatterns = [
path('admin/', admin.site.urls),
path('api/v1/', include('posts.urls')),
path('api-auth/', include('rest_framework.urls')),
path('api/v1/rest-auth/', include('rest_auth.urls')),
path('api/v1/rest-auth/registration/',
include('rest_auth.registration.urls')),
path('docs/', include_docs_urls(title='Blog API')), # new path('schema/', schema_view),
]
就是这样！ 现在，通过 http://127.0.0.1:8000/docs/ 导航到新路线，您可以看到我们 API 的友好得多的直观视图。 如果您在此处看到错误消息，请使用 Control + c 停止本地服务器，然后使用 python manage.py runserver 重新启动它。
作为一种小的整理方法，您可能已经注意到，我们在 urls.py 文件中重复了标题。 由于我们一直希望尽可能地保持DRY 原则，因此我们为 API 标题添加变量 API_TITLE。 同时，我们还要为我们的文档添加 API 描述。
# blog_project/urls.py
from django.contrib import admin
from django.urls import include, path
from rest_framework.documentation import include_docs_urls
from rest_framework.schemas import get_schema_view
API_TITLE = 'Blog API' # new
API_DESCRIPTION = 'A Web API for creating and editing blog posts.' # new
schema_view = get_schema_view(title=API_TITLE) # new
urlpatterns = [
path('admin/', admin.site.urls),
path('api/v1/', include('posts.urls')),
path('api-auth/', include('rest_framework.urls')),
path('api/v1/rest-auth/', include('rest_auth.urls')),
path('api/v1/rest-auth/registration/',
include('rest_auth.registration.urls')),
path('docs/', include_docs_urls(title=API_TITLE,
description=API_DESCRIPTION)), # new
path('schema/', schema_view), ]
好多了。 现在，如果您刷新文档页面，则可以看到标题下的描述。
我们还可以通过多种方式与此文档进行交互。 例如，尝试单击页面顶部列表旁边的“交互”按钮。 将会弹出一个空白窗口。
单击按钮“ SEND REQUEST”，它将调用 API 端点。
以相同的方式，我们可以与所有可用的并完整记录的 API 端点进行交互。
Django REST Swagger
尽管内置的 Django REST Framework 文档相当不错，但是还有一种更好的方法。 我们可以使用出色的第三方Django REST Swagger 程序包通过称为 Swagger 的工具来实现OpenAPI规范。这是用于记录RESTful API 的当前最佳实践方法。
首先，停止本地服务器 Control + c。 然后在命令行上安装 django-rest-swagger。
(blogapi) $ pipenv install django-rest-swagger==2.2.0
将其添加到 blog_project/settings.py 中的 INSTALLED_APPS 设置中，因为它是第三方应用程序，而不是具有诸如 coreapi 之类的内置支持的应用程序。
# blog_project/settings.py
INSTALLED_APPS = [
'django.contrib.admin',
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.staticfiles',
'django.contrib.sites',
# 3rd-party apps
'rest_framework',
'rest_framework.authtoken',
'rest_framework_swagger', # new
'allauth',
'allauth.account',
'allauth.socialaccount',
'rest_auth',
'rest_auth.registration',
# Local
'posts.apps.PostsConfig',
]
最后，我们想用 blog_- project/urls.py 中的新 Swagger 模式替换默认模式。 在文件顶部导入 get_swagger_view。 现在更新 schema_view 以使用Swagger，因此 get_swagger_view 不是先前的 get_schema_view。 并注释掉 schema/ 的旧方法，为 swagger-docs 添加新方法。
# blog_project/urls.py
from django.contrib import admin
from django.urls import include, path
from rest_framework.documentation import include_docs_urls
from rest_framework.schemas import get_schema_view
from rest_framework_swagger.views import get_swagger_view # new
API_TITLE = 'Blog API'
API_DESCRIPTION = 'A Web API for creating and editing blog posts.'
schema_view = get_swagger_view(title=API_TITLE) # new
urlpatterns = [
path('admin/', admin.site.urls),
path('api/v1/', include('posts.urls')),
path('api-auth/', include('rest_framework.urls')),
path('docs/', include_docs_urls(title=API_TITLE,
description=API_DESCRIPTION)),
# path('schema/', schema_view), # new
path('swagger-docs/', schema_view), # new ]
确保服务器正在运行（ python manage.py runserver ），导航至位于 <http://127.0.0.1:8000/swagger-docs/> 的新 Swagger 路由，您将看到结果。
但是您可能要问的数据在哪里？ 单击 v1 以显示所有受支持的端点和可用的 HTTP 方法的下拉列表。
Swagger Log In and Log Out
可以在官方文档中找到多种自定义 Swagger 的方法。 我们应该更新的另一项设置是登录和注销。 如果您以前尝试单击右上角的“会话登录”按钮，则该按钮无效。 我们需要指定正确的登录和注销路由。
在 blog_project/settings.py 文件的底部，添加以下 Swagger 设置
# blog_project/settings.py
SWAGGER_SETTINGS = {
'LOGIN_URL': 'rest_framework:login',
'LOGOUT_URL': 'rest_framework:logout',
}
现在，“登录会话”和“注销”按钮将正常工作。
总结
添加文档是任何 API 的重要组成部分。 无论是在团队内部还是在开源项目中，这都是同行开发人员首先要看的东西。 通过自动化工具，因此只需少量配置即可确保 API 包含准确的最新文档。
