Django 入门：模式和文档

模式和文档

现在我们已经完成了API，我们需要一种向其他人快速准确地记录其功能的方法。 毕竟，在大多数公司和团队中，使用该API的开发人员与最初构建该API的开发人员不同。 幸运的是，有自动化工具可以为我们解决这个问题。
模式是机器可读的文档，概述了它们支持的所有可用API端点，URL和HTTP谓词（GET，POST，PUT，DELETE等）。 文档是添加到架构中的东西，它使人类更易于阅读和使用。 在本章中，我们将向我们的Blog项目添加一个架构，然后添加两种不同的文档编制方法。 到最后，我们将实现一种自动化的方式来记录对API的当前和将来的任何更改。
提醒一下，这是我们当前API端点的完整列表：

模式

从​​3.9版​​生成架构的当前方法。

但是，由于这是一个迭代过渡，因此我们将在项目中使用传统的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​​。这是用于记录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包含准确的最新文档。