自动生成API文档
一、doc文档
1.1 安装
需要安装以下几个包(如果有虚拟环境需要进入虚拟环境安装)
- coreapi(必须)
- Pygments(可选)
- Markdown(可选)
1.2添加配置
3.10版本以上的DRF,需要添加配置信息,在setting.py文件的REST_FRAMEWORK中,添加如下代码:
REST_FRAMEWORK = {
# 指定用于支持coreapi的Schema
'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
}
在主路由中添加路由条目。修改url.py文件
from rest_framework.documentation import include_docs_urls
urlpatterns = [
path('docs/', include_docs_urls(title='API接口文档', description='xxx描述'))
]
此时,访问http://127.0.0.1:8000/docs/就可以看到我们的接口文档了。
1.3给每个接口添加注释
在视图类中添加注释,格式为:方法名:注释。
class ProjectViewSet(viewsets.ModelViewSet):
"""
list:
获取项目列表数据
retrieve:
获取项目详情数据
...
"""
二、swagger文档
1.1 安装
使用如下命令安装drf-yasg(如果有虚拟环境需要进入虚拟环境安装)
pip install drf-yasg
1.2 注册
在settings.py中注册子应用。
INSTALLED_APPS = [
...
'drf_yasg',
]
1.3 添加路由
在全局路由文件urls.py文件中添加如下代码:
from drf_yasg.views import get_schema_view
from drf_yasg import openapi
schema_view = get_schema_view(
openapi.Info(
title="Lemon API接口文档平台", # 必传
default_version='v1', # 必传
description="这是一个美轮美奂的接口文档",
terms_of_service="http://api.keyou.site",
contact=openapi.Contact(email="[email protected]"),
license=openapi.License(name="BSD License"),
),
public=True,
# permission_classes=(permissions.AllowAny,), # 权限类
)
urlpatterns = [
...
re_path(r'^swagger(?P<format>\.json|\.yaml)$', 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'),
]
此时,访问http://127.0.0.1:8000/swagger/就可以看到我们的swagger接口文档了。