DRF-YASG 项目配置详解：Swagger 与 ReDoc 的完整设置指南

DRF-YASG 项目配置详解：Swagger 与 ReDoc 的完整设置指南

drf-yasg Automated generation of real Swagger/OpenAPI 2.0 schemas from Django REST Framework code. 项目地址: https://gitcode.com/gh_mirrors/dr/drf-yasg

前言

在现代 API 开发中，良好的文档是项目成功的关键因素之一。DRF-YASG 作为 Django REST framework 的扩展，提供了强大的 API 文档生成功能。本文将深入解析 DRF-YASG 的配置系统，帮助开发者根据项目需求定制 Swagger 和 ReDoc 文档界面。

基础配置

DRF-YASG 的配置主要通过 Django 的 settings.py 文件实现，支持两种主要的配置字典：

SWAGGER_SETTINGS = {
    # Swagger 相关配置
}

REDOC_SETTINGS = {
    # ReDoc 相关配置
}

URL 配置项支持多种格式，包括视图名称、带参数的视图名称元组或直接 URL 字符串。

Swagger 配置详解

1. 默认类配置

DRF-YASG 提供了多个可自定义的默认类，用于控制文档生成过程：

• DEFAULT_GENERATOR_CLASS: 指定默认的 OpenAPI 模式生成器
• DEFAULT_AUTO_SCHEMA_CLASS: 控制端点操作生成的默认类
• DEFAULT_FIELD_INSPECTORS: 序列化器字段检查器列表
• DEFAULT_FILTER_INSPECTORS: 过滤器检查器列表
• DEFAULT_PAGINATOR_INSPECTORS: 分页器检查器列表
• DEFAULT_SPEC_RENDERERS: 模式渲染器列表

这些配置项允许开发者深度定制文档生成过程，适应各种复杂场景。

2. 文档属性配置

• EXCLUDED_MEDIA_TYPES: 排除特定的 MIME 类型
• DEFAULT_INFO: 默认的 API 信息对象
• DEFAULT_API_URL: 默认 API 基础 URL

3. 认证授权配置

• USE_SESSION_AUTH: 启用/禁用 Django 会话认证
• LOGIN_URL/LOGOUT_URL: 认证相关 URL
• SECURITY_DEFINITIONS: 安全定义配置
• SECURITY_REQUIREMENTS: 全局安全要求

4. Swagger UI 高级配置

Swagger UI 提供了丰富的可配置选项：

• UI 行为控制:

  • PERSIST_AUTH: 持久化认证数据
  • REFETCH_SCHEMA_WITH_AUTH: 认证后重新获取模式
  • FETCH_SCHEMA_WITH_QUERY: 使用查询参数获取模式

• 显示排序:

  • OPERATIONS_SORTER: 操作排序方式
  • TAGS_SORTER: 标签排序方式

• UI 展示:

  • DOC_EXPANSION: 默认展开级别
  • DEEP_LINKING: 深度链接支持
  • DEFAULT_MODEL_RENDERING: 模型渲染方式
  • SHOW_EXTENSIONS: 显示扩展字段

• OAuth2 集成:

  • OAUTH2_REDIRECT_URL: OAuth2 重定向 URL
  • OAUTH2_CONFIG: OAuth2 配置参数

ReDoc 配置详解

ReDoc 提供了不同于 Swagger UI 的文档展示方式，主要配置包括：

• SPEC_URL: 文档源 URL
• LAZY_RENDERING: 启用延迟渲染（大型 API 推荐）
• HIDE_HOSTNAME: 隐藏主机名
• EXPAND_RESPONSES: 默认展开的响应码
• PATH_IN_MIDDLE: 路径显示位置
• NATIVE_SCROLLBARS: 使用原生滚动条
• REQUIRED_PROPS_FIRST: 必填属性优先显示

最佳实践建议

1. 安全性考虑:

   • 生产环境应考虑禁用 PERSIST_AUTH
   • 谨慎配置 SECURITY_DEFINITIONS

2. 性能优化:

   • 大型 API 文档启用 LAZY_RENDERING
   • 考虑使用 NATIVE_SCROLLBARS

3. 用户体验:

   • 根据用户群体调整 DOC_EXPANSION
   • 合理配置 DEFAULT_MODEL_RENDERING

4. 开发环境:

   • 启用 DEEP_LINKING 方便分享特定端点
   • 配置适当的 OPERATIONS_SORTER 提高可读性

总结

DRF-YASG 提供了极其灵活的配置系统，几乎可以满足所有 API 文档展示的需求。通过合理配置 SWAGGER_SETTINGS 和 REDOC_SETTINGS，开发者可以创建出既美观又实用的 API 文档界面，极大提升 API 的使用体验。

理解这些配置项的含义和相互关系，将帮助您根据项目特点打造最适合的文档解决方案，无论是简单的内部 API 还是复杂的企业级接口都能应对自如。

drf-yasg Automated generation of real Swagger/OpenAPI 2.0 schemas from Django REST Framework code. 项目地址: https://gitcode.com/gh_mirrors/dr/drf-yasg