分享自己抽取的一个 django app 部署展示 swagger 文档

[cocoakekeyu]

Swaggerdoc

说明

这是一个简便的 django app 将 swagger ui 搬到项目中展示。开发人员只需将 swagger 文档放到项目指定目录，即可打开相应的 URL 查看 swagger 文档，非常适合使用 Django 开发的项目，在开发过程同时编写文档，并同步更新到项目中，团队其他人员也可以同时看到最新修改的文档。

用法

Django APP 为swaggerdoc，像其他 APP 一样将该目录放到项目目录中。然后准备一些配置：

1. 在项目 setting 中的 INSTALLED_APPS 列表写入'swaggerdoc', 主要便于 Django 自动查找'swaggerdoc'APP 中的 static 和 templates 目录下面的文件。该 APP 没有 models 文件，如果不想写入 INSTALLD_APPS ，需要将静态文件目录包含 swaggerdoc 内的static和templates目录。
2. 在项目 setting 中设置DOC_DIR, 存放 swagger 文档的目录。也可以不设置，默认为项目目录下的docs文件夹。
3. 设置STATICFIELS_DIRS，包含第 2 点的DOC_DIR。如设置为os.path.join(BASE_DIR, 'docs')，使得 Django 可以找到该目录下的 swagger 文档。
4. 设置url patterns, 在项目的urls.py文件设置 swagger 文档访问路径，包含swaggerdoc.urls即可。如: url(r'^api/doc/', include('swaggerdoc.urls')。

这样，启动项目服务器，即可打开浏览器访问{服务其地址}/api/doc就可以看到项目文档了。

效果图如下：

代码是一个完整的 django 工程，提供可运行的示例, 直接 git clone 试运行。

github ： https://github.com/cocoakekeyu/swaggerdoc