1 对接文档

程序员们通常使用哪个方式沟通？本文首先讨论了为何需要清晰的API文档，特别是当API使用者与构建者不同时。然后提到了Schema作为机器可读的文档格式，概述API端点、URL和HTTP动词。

文章详细阐述了如何利用Django REST框架的OpenAPI模式，以及安装PyYAML和uritemplate来生成静态或动态模式。此外，还介绍了使用drf-yasg库来创建更友好的API文档，并提供了配置示例。

假如现在已经有了一部分API，我们需要一种方法来快速记录其功能，并且准确地给别人。

毕竟，在大多数公司和团队中，使用API的开发人员与最初构建它的开发人员一般不同。

这对我们来说幸运的是，有自动工具可以处理。
比如schema是机器可读的文档，概述了所有可用的API端点，URL和支持的HTTP动词（GET，POST，PUT，DELETE等）。

将文档简化为人类易于阅读和使用的结构。我们将添加一个模式添加到项目中，然后添加两种不同的文档编制方法。到最后我们将实现一种自动化的方式来记录我们的 API 当前和将来的 任何变化。

比如现在我们有如下的接口,已有的大致api列表

  |Endpoint |HTTP Verb|
|--------------------------------------|---------|
|/                                     |GET |
|/:pk/                                 |GET |
|users/                             |GET |
|users/:pk/                         |GET |
|/rest-auth/registration             |POST |
|/rest-auth/login                     |POST |
|/rest-auth/logout                     |GET |
|/rest-auth/password/rest_framework                  |POST |
|/rest-auth/password/reset/confirm                 |POST |

2 模式 Schemas

   django rest framework 已经切换到OpenAPI模式

第一步是同时安装PyYAML和uritemplate PyYAML 这将改变我们的架构，转换为OpenAPI格式是基于YAML的，而uritemplate将参数添加到URL路径。

接下来，我们可以选择：生成静态模式或动态模式。如果您的API不会经常更改，因此可以定期生成静态模式并从静态服务器提供服务档案以取得强大效能.

但是，如果您的API确实经常更改，则可以考虑动态选项。我们将在此处实现两者。 安装依赖包

            pip install pyyaml==5.3.1 uritemplate==3.0.1

首先，是使用generatechema管理命令的静态模式方法。我们可以将结果输出到文件： openapi-schema.yml.

静态方法：

 python manage.py generateschema > openapi-schema.yml

如果您打开该文件，则该文件会很长，而且不友好。但是对于电脑来说，这是完美的格式化。

对于动态方法，

通过在顶部导入get_schema_view来更新config/urls.py

然后在openapi创建专用路径。标题，描述和版本可以是根据需要定制。修改全局配置 config/url.py

• 模板静态处理api

    from rest_framework.schemas import get_schema_view 
        ...
        path('openapi', get_schema_view( # new
            title="Blog API",
            description="A sample API for learning DRF",
            version="1.0.0"), name='openapi-schema'),
        ]
  

现在访问 http://127.0.0.1:2000/openapi， 以查看变化，可以看到不太友好。

• 动态方法 翻译api 为文档给其他开发者

  Django REST框架还带有内置的API文档功能，可翻译，对其他开发人员而言，将架构转换为更友好的格式。

  或者使用第三方包 drf-yasg， 它有更多功能。 这里将使用第三方包 drf-yasg

3 使用依赖库

• 1,安装：pip install install drf-yasg==1.17.1

• 2,注册，使用第三方包都需要注册，不要忘记注册第三方包，否则运行时可能找不到该功能：

   # config/settings.py
    INSTALLED_APPS = ['drf_yasg', # new]
  

• 3, 更新urls.py 路由

第三步，更新我们的项目级别的urls.py文件。 我们可以替换DRF，从drf_yasg中获取get_schema_view以及导入openapi。我们还将添加DRF并允许使用其他选项。

schema_view变量已更新，并包含其他字段，例如terms_of_service联系人和许可。
然后在我们的urlpatterns下，为Swagger和ReDoc添加路径,config/urls.py

其他导入和配置不变不变

    from rest_framework import permissions # new
    from drf_yasg.views import get_schema_view # new
    from drf_yasg import openapi # new

    schema_view = get_schema_view( # new
        openapi.Info(
        title="Blog API",
        default_version="v1",
        description="A sample API for learning DRF",
        terms_of_service="https://www.google.com/policies/terms/",
        contact=openapi.Contact(email="hello@example.com"),
        license=openapi.License(name="BSD License"),
        ),
        public=True,
        permission_classes=(permissions.AllowAny,),
        )
    ... 

访问http://127.0.0.1:2000/swagger/ 和 http://127.0.0.1:2000/redoc/

他们非常全面，并阐明了更多可以取决于API的需求.

文档是任何API的重要组成部分。通常，这是开发人员的第一件事在团队内部还是在开源项目中查看。

得益于自动化工具，我们通过第三方库的使用 仅需要少量的配置 旧可以确保您的API拥有准确的最新文档Django REST框架。

在三个不同项目的过程中-库API，Todo API和博客API-我们从头开始逐步构建更复杂的Web API。

在此过程的每一步中，Django REST框架都提供了内置功能，使我们更轻松。

官方文档是进一步探索的绝佳资源。现在您已经掌握了基本知识.

4 小结

传统的Django测试可以而且应该可应用于任何Web API项目，但Django REST中还有一整套工具仅用于测试API请求的框架。

可以参考实现官方DRF教程中介绍的pastebin API。

第三方包对于Django REST Framework开发至关重要，而对于Django本身。完整清单可以在Django Packages上找到，也可以使用在Github上的awesome-django.

参考：

 https://www.django-rest-framework.org/

 https://djangopackages.org/