drf-yasg 项目使用教程

drf-yasg 项目使用教程

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

1. 项目的目录结构及介绍

drf-yasg 是一个用于自动生成 Swagger/OpenAPI 2.0 规范的开源项目，它基于 Django Rest Framework。以下是项目的目录结构及文件介绍：

drf-yasg/
├── .github/              # GitHub 相关配置文件
├── docs/                 # 项目文档
├── requirements/         # 项目依赖文件
├── screenshots/          # 项目截图
├── scripts/              # 脚本文件
│   └── linters/          # 代码检查脚本
├── src/                  # 源代码目录
│   └── drf_yasg/         # drf-yasg 核心代码
├── testproj/             # 测试项目
├── tests/                # 单元测试
├── .codecov.yml          # CodeCov 配置文件
├── .coveragerc           # Coverage 配置文件
├── .cspell.json          # cspell 配置文件
├── .editorconfig          # 编辑器配置文件
├── .gitattributes         # Git 属性配置文件
├── .gitignore            # Git 忽略文件
├── .readthedocs.yml       # Read the Docs 配置文件
├── CONTRIBUTING.rst       # 贡献指南
├── LICENSE.rst           # 许可证文件
├── MANIFEST.in            # 打包配置文件
├── Procfile              # Heroku 的进程文件
├── README.rst            # 项目说明文件
├── app.json              # 应用配置文件
├── package-lock.json     # 包锁定文件
├── package.json          # 包文件
├── pyproject.toml        # Python 项目配置文件
├── requirements.txt      # 项目依赖文件
├── runtime.txt           # 运行环境文件
├── setup.cfg             # 打包配置文件
├── setup.py              # 打包文件
└── tox.ini               # tox 配置文件

2. 项目的启动文件介绍

项目的启动主要依赖于 src/drf_yasg 目录下的 Python 文件。具体来说，以下是几个关键的启动文件：

• __init__.py: 初始化 drf-yasg 模块。
• app.py: 定义了 drf-yasg 的 Django 应用。
• views.py: 包含了生成 Swagger/OpenAPI 规范的视图。

在 Django 项目中，你需要在 settings.py 文件中添加 drf_yasg 到 INSTALLED_APPS 中，并在 urls.py 中配置相关路由。

3. 项目的配置文件介绍

项目的配置主要通过以下几个文件进行：

• settings.py: 这是 Django 项目的配置文件，你可以在其中设置 INSTALLED_APPS 来包含 drf_yasg，并配置其他 Django 设置。

  INSTALLED_APPS = [
      ...
      'drf_yasg',
      ...
  ]
  

• urls.py: 这是 Django 项目的 URL 配置文件，你需要在其中引入 drf_yasg.views 并定义路由来访问 Swagger/UI。

  from django.urls import path
  from drf_yasg.views import get_schema_view
  from drf_yasg import openapi
  from rest_framework.permissions import AllowAny
  
  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=(AllowAny,),
  )
  
  urlpatterns = [
      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'),
      ...
  ]
  

确保在配置过程中遵循项目的官方文档以获取更多详细的配置选项。

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