Django-自动生成API文档

自动生成API文档

  • 一、doc文档
    • 1.1 安装
    • 1.2添加配置
    • 1.3给每个接口添加注释
  • 二、swagger文档
    • 1.1 安装
    • 1.2 注册
    • 1.3 添加路由


一、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/就可以看到我们的接口文档了。
Django-自动生成API文档_第1张图片

1.3给每个接口添加注释

在视图类中添加注释,格式为:方法名:注释。

class ProjectViewSet(viewsets.ModelViewSet):
    """
    list:
    获取项目列表数据

    retrieve:
    获取项目详情数据
    ...
    """

Django-自动生成API文档_第2张图片

二、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\.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接口文档了。
Django-自动生成API文档_第3张图片

你可能感兴趣的:(Django)