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

本文介绍: Swagger 是一种用于的开源框架，可以帮助开发者快速构建和文档化 API。Swagger 文档提供了一种自动生成和可视化 API 文档的方式，使得 API 的设计和使用更加简单和易懂。Swagger 文档通过描述 API 的路径、参数、请求体、响应和错误码等信息，让开发者可以快速了解 API 的设计和使用方式，方便开发者进行 API 的集成和调用。Swagger 2.0 是 Swagger 规范的第二个版本，引入了许多新的功能和改进。

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

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。

pip install drf-spectacular

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

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

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}

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

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

显示所有内容

声明：本站所有文章，如无特殊说明或标注，均为本站原创发布。任何个人或组织，在未征得本站同意时，禁止复制、盗用、采集、发布本站内容到任何网站、书籍等各类媒体平台。如若本站内容侵犯了原著者的合法权益，可联系我们进行处理。

Swagger 文档介绍

drf-yasg 介绍

drf-spectacular介绍

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

安装 drf-spectacula

必要的配置

自定义OpenApi 描述

生成 yaml 文件

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

发表回复取消回复