这次课主要讲解Django自动化生成API文档的开发，Django有自带的内置的API文档生成方式，我们主要介绍第三方软件包drf-yasg，是基于和规范的文档自动化生成工具，能够生成比原生更为友好的文档界面。
目前的兼容性如下：
-
Django Rest Framework: 3.10, 3.11, 3.12
-
Django: 2.2, 3.0, 3.1
-
Python: 3.6, 3.7, 3.8, 3.9
我们使用的Django Rest Framework版本是3.9版本，Django是3.2版本，Python是3.8版本，我们先试一试兼容性会不会存在问题。
drf-yasg模块安装
drf-yasg模块的安装我们还是使用pip包管理工具，目前drf-yasg发展到1.20版本，笔者使用的1.70版本，安装命令为：
我们还是采用pip3 list | grep dry-yasg查询我们是否安装好drf-yasg这个模块。安装软件包不做过多介绍了。
drf-yasg的配置相对比较简单，在全局urls.py中把drf-yas模块和url路径配置进去。我们先把代码放上来，再来介绍：
上面代码中，我们新增的部分是：
配置完成后运行，笔者访问http://127.0.0.1:8000/redoc/，或者http://127.0.0.1:8000/SWAGger/的时候，我们只能看到页面的零星信息，但是接口定义是看不到，这里遇到一个报错，报错信息如下：
解决方式一：
我们虽然使用了drf-yasg，在settings文件中忘记了添加drf-yasg应用，因此会出现上面的错误，如果我们把drf-yasg添加到INSTALLED_APPS中就不会出现以上错误。代码如下：
从不同的角度解决问题可以加深对Django技术原理的理解。
解决方式二：
这个报错很直接，就是访问/Users/sushangting/devel/static/drf-yasg下的静态资源是访问不到，因此我们需要把drf-yasg下的这些文件放到我们可以访问的static目录下即可。我们的python软件包都安装在/Library/Python/3.8/site-packages目录下，包括drf-yasg和rest_framework，我们只要把/Library/Python/3.8/site-packages/drf_yasg/static下的内容拷贝到/Library/Python/3.8/site-packages/rest_framework/static目录下即可。
测试接口
在urls文件中我们发现配置了三种访问路径，其实就是三种UI展示的风格。
url(r”^docs/”, include_docs_urls(title=”My API title”)),path(“SWAGger/”, schema_view.with_ui(“SWAGger”, cache_timeout=0), name=”schema-SWAGger”),path(“redoc/”, schema_view.with_ui(“redoc”, cache_timeout=0), name=”schema-redoc”),
我们分别访问一下，看一下接口的web页面：
首先是：http://127.0.0.1:8000/docs/，这个页面是django-rest-framework 自动生成接口说明文档，是个内置的OpenAPI方案，从rest_framework.documentation模块中导入include_docs_urls方法（from rest_framework.documentation import include_docs_urls）截图如下：
外一个：http://127.0.0.1:8000/SWAGger/，这个使用的是drf-yasg模块，从drf_yasg.views视图中导入get_schema_view方法（from drf_yasg.views import get_schema_view），然后初始化和配置path路径，截图如下：
还有一个是：http://127.0.0.1:8000/redoc/#tag/devtemplate，截图如下：
从页面上即可测试，这里不做过多介绍。
drf-yasg扩展内容
这里我们还想对drf-yasg做些回顾。最好的学习方式就是看官网的教程https://drf-yasg.readthedocs.io/en/stable/，官网是英文的，大家也可以搜索看一些专门针对drf-yasg的介绍。我们主要根据官网进行介绍。
drf-yasg – Yet another SWAGger generator。
安装
pip install -U drf-yasg
-U就是 –upgrade，意思是如果已安装就升级到最新版。
:
:
有四种方式的页面:
-
JSON视图页面
-
YAML视图格式
-
SWAGger-ui 视图格式
-
ReDoc视图格式
配置
a. parameters参数说明
-
– SWAGger API 接口信息描述，缺省值 -
– API url -
– 传递给SchemaGenerator -
– 传递给SchemaGenerator -
– 访问权限 -
-验证器 onlyis currently supported -
– schema generator 类，是的子类 -
– 认证类设置 -
– 权限类设置
b. options
-
– 采用指定的UI页面风格渲染页面, -
-
c. and
还可以配置更多的参数settings file. See https://drf-yasg.readthedocs.io/en/stable/settings.htm。