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/
