DRF - 又一个 Swagger 生成器 2

从 Django REST 框架代码自动生成真正的 Swagger/OpenAPI 2.0 模式。

注意

原来的 drf-yasg存储库现在再次得到维护。这个 repo 将保持原样为仍在使用它的人提供服务。

请迁移回使用原始存储库并提交贡献。

地位

资源	盾牌
项目
出版商
下载
提高

兼容性

特征

• 完全支持嵌套的序列化器和模式

• 响应模式和描述

• 与代码生成工具兼容的模型定义

• 规范生成过程中所有点的自定义挂钩

• 用于规范的 JSON 和 YAML 格式

• 捆绑最新版本的swagger-ui 和redoc以查看生成的文档

• 架构视图开箱即用可缓存

• 生成的 Swagger 架构可以通过swagger-spec-validator自动验证

• URLPathVersioning使用和 支持 Django REST Framework API 版本控制NamespaceVersioning；当前不支持其他 DRF 或自定义版本控制方案

截图

完全嵌套的请求和响应模式

在 redoc 和 swagger-ui 之间进行选择

模型定义

安装

从 pypi 安装包：

pip install drf-yasg2

鉴于手动自定义生成的模式的方法众多，验证结果以确保它仍然符合 OpenAPI 2.0 是有意义的。为此，使用 Python Swagger 库在生成点提供验证，并且可以通过传递validators=['ssv']给get_schema_view; 如果生成的模式无效，SwaggerValidationError则处理编解码器会引发 a。

要提供内置验证机制，您可以安装额外的要求：

pip install drf-yasg2[validation]

用法

查看现场演示！

将包添加到 INSTALLED_APPS：

   INSTALLED_APPS = [
      ...
      'drf_yasg2',
      ...
   ]

将端点添加到 urlpatterns：

   from django.urls import path, re_path
   from rest_framework import permissions
   from drf_yasg2.views import get_schema_view
   from drf_yasg2 import openapi

   ...

   schema_view = get_schema_view(
      openapi.Info(
         title="Snippets API",
         default_version='v1',
         description="Test description",
         terms_of_service="https://www.google.com/policies/terms/",
         contact=openapi.Contact(email="contact@snippets.local"),
         license=openapi.License(name="BSD License"),
      ),
      public=True,
      permission_classes=(permissions.AllowAny,),
   )

   urlpatterns = [
      re_path(r'^swagger(?P<format>\.json|\.yaml)$', schema_view.without_ui(cache_timeout=0), name='schema-json'),
      path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
      path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
      ...
   ]

这暴露了 4 个端点：

• 您的 API 规范的 JSON 视图，位于/swagger.json
• 您的 API 规范的 YAML 视图，位于/swagger.yaml
• 您的 API 规范的 swagger-ui 视图，位于/swagger/
• API 规范的 ReDoc 视图，位于/redoc/

文档

完整文档和变更日志中提供了更多详细信息。

要在本地生成文档：

scripts/docs.sh

测试

运行测试：

tox

贡献

请阅读CONTRIBUTING.md了解我们的行为准则以及提交拉取请求的流程的详细信息。

版本控制

SemVer用于版本控制。有关可用版本的列表，请参阅此存储库上的标签。

作者

这个项目来自drf-yasg。归功于 Cristi Vîjdea和原始贡献者。

• Cristi Vîjdea -初始工作- Cristi Vîjdea

• Joel Lefkowitz -这个分支的维护者- Joel Lefkowitz

非常感谢参与这个项目的贡献者。看看贡献！

执照

该项目根据 BSD 3-Clause License 获得许可 - 请参阅LICENSE.md文件了解详细信息