1、API 接口文档的几种规范格式

前后端分离项目中，使用规范、便捷的API接口文档工具，可以有效提高团队工作效率。

标准化的API文档的益处：

• 允许开发人员以交互式的方式查看、测试API接口，以方便使用
• 将所有可暴露的API接口进行分类，整齐的文档便于快速查找和使用

当前流行的REST API接口文档格式有： Swagger(当前已成为OpenAPI3.0规范）, redoc等。

2、自动生成API接口的工具

Django-Rest-Framework 内置了1个 API 文档生成模块： rest_framework.documentation

但笔者推荐使用第３方工具： drf-spectacular , drf-yasg，可以生成更规范的Swagger, ReDoc格式的API接口文档

3、使用 drf_yasg 自动生成 Swagger, ReDoc API文档

先准备好Django-REST-Framework项目，编写并测试好至少1个API 测试接口。

关于Django-REST-Framework 的使用，可以在网上搜索相关教程

Step-1, 安装 drf-yasg 库

pip install coreapi
pip install -U drf-yasg[validation]

Step-2 增加 drf_yasg 配置

在项目的 myproject/myproject/settings.py 中添加如下配置

INSTALLED_APPS = ['django.contrib.admin','django.contrib.auth','django.contrib.contenttypes','django.contrib.sessions','django.contrib.messages','django.contrib.staticfiles',    'rest_framework','drf_yasg','quickstart', # app name 'corsheaders','student_rest',  # new app 
]REST_FRAMEWORK = {'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
}

Step-3 添加 drf_yasg 的 url

drf-yasg 可以自动识别通过 url 暴露的 函数视图, CBV类视图, APIview, Viewset 通用视图类的接口, 无须在视图层添加额外代码。仅须将drf_yasg 的url 添加到django的路由配置中即可。

添加如下代码至 myproject/myproject/urls.py 中

from drf_yasg.views import get_schema_view
from drf_yasg import openapi# Swagger documentation setup
schema_view = get_schema_view(openapi.Info(title="Rest API",default_version='v1',description="Test description",terms_of_service="https://www.google.com/policies/terms/",contact=openapi.Contact(email="contact@snippets.local"),license=openapi.License(name="BSD License"),),public=True,permission_classes=(permissions.AllowAny,),)urlpatterns = [path('swagger<format>/', schema_view.without_ui(cache_timeout=0), name='schema-json'),path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),]

Step-4 测试

启动项目：

python manager.py runserver

在浏览器中输出下列url, 可以看到所有API均以 redoc 格式呈现，每个接口均有说明与示例, 可以进行测试。

http://127.0.0.1:8000/redoc/

以 swagger 格式查看, 除了查看外，支持测试，也可以查询过滤接口，相当方便

http://127.0.0.1:8000/swagger/

4、Django-REST-Framework内置 API 文档工具

DRF内置的API文档工具生成的API文档也非常规范，也是Python开源社区最流行的API文档格式。 但笔者在测试时，发现需要安装 coreapi 库

安装 coreapi

pip install coreapi 

添加 rest_framework.documentation 路由

在 myproject/myproject/urls.py 中引入预定义的url ， 再添加路由即可

from rest_framework.documentation import include_docs_urls urlpatterns = [....path('docs/', include_docs_urls(title='api-docs')),]

测试接口： http://127.0.0.1:8000/docs/