Django-REST-Framework 如何快速生成Swagger, ReDoc格式的 REST API 文档

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/