Django 快速整合 Swagger：实用步骤和最佳实践

Django ，作为 Python 编写的一个优秀的开源 Web 应用框架，特别适用于快速开发的团队。对于很多场景来说，我们需要一份 API 文档，好处实在太多了：

提高开发效率：开发者可以基于 API 文档 快速学习和尝试 API，同时 Swagger 文件也可以在许多不同的平台上从代码注释中自动生成，减少了手动编写文档的时间和精力。
方便接口测试：基于 API 文档可以生成客户端 SDK 代码，用于不同平台上的实现，便于开发者进行接口测试。
优化团队协作：OpenAPI 有一个强大的社区，里面有许多强悍的贡献者，可以帮助团队更好地进行协作开发。
方便接口管理：如果能够自动化生成文档，就可以减少手动编写文档和维护文档的麻烦，每次接口有变动时也可以自动更新文档，便于接口的管理和维护。

Swagger 文档介绍

Swagger 是一种用于 RESTful API 的开源框架，可以帮助开发者快速构建和文档化 API。Swagger 文档提供了一种自动生成和可视化 API 文档的方式，使得 API 的设计和使用更加简单和易懂。Swagger 文档通过描述 API 的路径、参数、请求体、响应和错误码等信息，让开发者可以快速了解 API 的设计和使用方式，方便开发者进行 API 的集成和调用。

Swagger 2.0 是 Swagger 规范的第二个版本，引入了许多新的功能和改进。与第一个版本相比，Swagger 2.0 添加了对 WebSockets、OAuth2、文件上传和下载等功能的支持，并且提高了描述 API 的精确度和可读性。Swagger 2.0 还提供了一种可扩展的方式，让开发者可以为自己的 API 添加自定义的元数据信息。

OpenAPI 3.0 是 Swagger 的下一代规范，为 RESTful API 提供了一种标准的描述和交互方式。与 Swagger 2.0 相比，OpenAPI 3.0 提供了更严格的模式验证和错误处理，支持更多的数据类型和协议，同时还提供了更好的安全性和可扩展性。OpenAPI 3.0 还提供了更好的分层描述方式，让开发者可以更好地组织和管理 API 的文档。

那么我们怎么在 Django 项目中集成 Swagger 功能呢？我介绍两个工具 drf-yasg 和 drf-spectacular。

drf-yasg 介绍

github.com/axnsan12/dr...

drf-yasg 也是一个基于 DRF 的 API 文档生成工具，同样支持 Swagger 2.0规范，并提供了自动生成文档和交互式文档页面的功能。它的特点是支持动态生成 Swagger UI，支持多种主题，可以自定义 API 文档样式，同时也提供了一些有用的功能，比如支持在文档中隐藏指定字段、支持在文档中添加额外的参数等。

drf-spectacular介绍

github.com/tfranzel/dr...

drf-spectacular 是一个基于 DRF 的 API 文档生成工具，支持 OpenAPI 3.0规范，并提供了自动生成文档和交互式文档页面的功能。它支持自定义的扩展和重载，可以满足不同项目的需求，同时还提供了一些有用的功能，比如支持通过代码自动注册 API 视图、支持自定义请求和响应验证器等。

使用 drf-spectacular 自动生成 OpenAPI 3.0 文档

如果新使用的是 OpenAPI 3.0 的文档，那么只能采用的是 drf-spectacular。

安装 drf-spectacula

python 复制代码

pip install drf-spectacular

必要的配置

在 settings.py 中声明

python 复制代码

INSTALLED_APPS = [ # ALL YOUR APPS'drf_spectacular',]

注册到 DRF Django Rest Framework

python 复制代码

REST_FRAMEWORK = {# YOUR SETTINGS'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',}

自定义OpenApi 描述

python 复制代码

SPECTACULAR_SETTINGS = {'TITLE': 'Your Project API','DESCRIPTION': 'Your project description','VERSION': '1.0.0','SERVE_INCLUDE_SCHEMA': False,# OTHER SETTINGS}

python 复制代码

REST_FRAMEWORK = { # YOUR SETTINGS'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',}
drf-spectacular ships with sane default settings that should work reasonably well out of the box. It is not necessary to specify any settings, but we recommend to specify at least some metadata.
SPECTACULAR_SETTINGS = {'TITLE': 'Your Project API','DESCRIPTION': 'Your project description','VERSION': '1.0.0','SERVE_INCLUDE_SCHEMA': False, # OTHER SETTINGS}

生成 yaml 文件

python 复制代码

./manage.py spectacular --color --file schema.yml

可视化打开 swagger 文件(可选)

python 复制代码

docker run -p 80:8080 -e SWAGGER_JSON=/schema.yml -v ${PWD}/schema.yml:/schema.yml swaggerapi/swagger-ui

我们可以看到 Swagger UI 如下：

最后感谢每一个认真阅读我文章的人，礼尚往来总是要有的，虽然不是什么很值钱的东西，如果你用得到的话可以直接拿走：

这些资料，对于【软件测试】的朋友来说应该是最全面最完整的备战仓库，这个仓库也陪伴上万个测试工程师们走过最艰难的路程，希望也能帮助到你！