Django项目使用Swagger自动生成API文档

简介

接口开发完成了，那么接下来需要编写接口文档。传统的接口文档编写都是使用word或者其他一些接口文档管理平台，这种形式接口文档维护更新比较麻烦，每次接口有变动时得手动修改文档。

Swagger是一个很好用的管理Api文档的工具，不仅仅Spring系列有自动化生成Swagger Api文档的工具包，Python同样也有(配置非常非常简单)！

Django接入Swagger
网上很多资料在介绍Django接入Swagger方法时，都是基于django-rest-swagger库进行讲解的，都殊不知，从2019年6月份开始，官方已经废弃了该库，在django 3.0中已经不支持该库了，取而代之的是全新的第三方drf-yasg库。

使用

1.安装

安装drf-yasg库

pip install drf-yasg

2.编辑设置文件

修改项目settings.py文件，添加api和drf_yasg。

INSTALLED_APPS = [
    ...
    'drf_yasg',   
]

3.路由设置

编辑url.py文件

# 配置swagger各个参数
from drf_yasg import openapi
from drf_yasg.views import get_schema_view

schema_view = get_schema_view(
    openapi.Info(
        title="XX项目 API",   # 名称
        default_version="版本 v1.0.0",   # 版本
        description="XX项目API交互文档由Swagger自动生成",  # 项目描述
    ),
    public=True,
)

urlpatterns = [
# 这两个url配置是一定要有的，用于生成ui界面，其它url正常定义就好
    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'),
]

4.测试访问

重启项目后访问

Swagger http://127.0.0.1:8000/swagger/

redoc ui http://127.0.0.1:8000/redoc/