关于django:Django-整合-Swagger实现快速-API-文档生成

Django，作为 Python 编写的一个优良的开源 Web 利用框架，特地实用于疾速开发的团队。对于很多场景来说，咱们须要一份 API 文档，益处切实太多了：

1. 进步开发效率：开发者能够基于 API 文档 疾速学习和尝试 API，同时 Swagger 文件也能够在许多不同的平台上从代码正文中主动生成，缩小了手动编写文档的工夫和精力。
2. 不便接口测试：基于 API 文档能够生成客户端 SDK 代码，用于不同平台上的实现，便于开发者进行接口测试。
3. 优化团队合作：OpenAPI 有一个弱小的社区，外面有许多强悍的贡献者，能够帮忙团队更好地进行合作开发。
4. 不便接口治理：如果可能自动化生成文档，就能够缩小手动编写文档和保护文档的麻烦，每次接口有变动时也能够自动更新文档，便于接口的治理和保护。

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 介绍

https://github.com/axnsan12/drf-yasg

drf-yasg 也是一个基于 DRF 的 API 文档生成工具，同样反对 Swagger 2.0 标准，并提供了主动生成文档和交互式文档页面的性能。它的特点是反对动静生成 Swagger UI，反对多种主题，能够自定义 API 文档款式，同时也提供了一些有用的性能，比方反对在文档中暗藏指定字段、反对在文档中增加额定的参数等。

drf-spectacular 介绍

https://github.com/tfranzel/drf-spectacular

drf-spectacular 是一个基于 DRF 的 API 文档生成工具，反对 OpenAPI 3.0 标准，并提供了主动生成文档和交互式文档页面的性能。它反对自定义的扩大和重载，能够满足不同我的项目的需要，同时还提供了一些有用的性能，比方反对通过代码主动注册 API 视图、反对自定义申请和响应验证器等。

应用 drf-spectacular 主动生成 OpenAPI 3.0 文档

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

1、装置 drf-spectacula

pip install drf-spectacular

2、必要的配置

在 settings.py 中申明

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

注册到 DRF Django Rest Framework

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

3、自定义 OpenApi 形容

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

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}

4、生成 yaml 文件

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

5、可视化关上 swagger 文件 (可选)

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

咱们能够看到 Swagger UI 如下：

更多 Swagger 应用技巧：

• 写给全栈工程师的 Swagger 基础教程
• 如何应用 Swagger 主动生成 API 文档