Django-自动生成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接口文档了。