Django REST Framework Yet Another Swagger Generator (drf-yasg) 安装与配置指南

Django REST Framework Yet Another Swagger Generator (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 的代码中生成真实的 Swagger 文档。这个项目使得开发人员能够轻松地创建和展示他们的 API 文档，帮助用户理解和使用 API。

主要编程语言：Python

2. 关键技术和框架

本项目使用的关键技术包括：

• Django REST Framework：一个强大的 Django 插件，用于构建 Web API。
• Swagger/OpenAPI：一种用于描述 API 的规范格式，使得 API 的交互更加标准化。
• Django：一个高级的 Python Web 框架，它鼓励快速开发和干净、实用的设计。

3. 安装和配置准备工作

在开始安装之前，请确保您的环境中已经安装了以下依赖：

• Python (版本 3.6+)
• Django (版本 2.2+)
• Django REST Framework (版本 3.10+) -pip (Python 包管理器)

详细安装步骤

步骤 1: 安装 drf-yasg

打开您的命令行工具，并运行以下命令来安装 drf-yasg：

pip install drf-yasg

如果您需要使用内置的验证机制，请安装包含验证依赖的包：

pip install drf-yasg[validation]

步骤 2: 配置 Django 项目

首先，在您的 Django 项目的 settings.py 文件中，添加 drf_yasg 到 INSTALLED_APPS：

INSTALLED_APPS = [
    # ...
    'django.contrib.staticfiles',  # 用于服务 Swagger UI 的 CSS/JS 文件
    'drf_yasg',
    # ...
]

然后，在 urls.py 文件中，添加以下代码来配置 URL 路由：

from django.urls import re_path
from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi

schema_view = get_schema_view(
    openapi.Info(
        title="示例 API",
        default_version='v1',
        description="示例 API 描述",
        terms_of_service="https://www.example.com/policies/terms/",
        contact=openapi.Contact(email="contact@example.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'),
    re_path(r'^swagger/$', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
    re_path(r'^redoc/$', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
    # ...
]

以上步骤将创建三个新的 URL 端点，分别用于访问 JSON 格式、YAML 格式的 API 规范，以及通过 Swagger UI 和 ReDoc UI 查看规范。

现在，您已经完成了 drf-yasg 的安装和基本配置。您可以启动 Django 开发服务器，并通过浏览器访问上述端点来查看生成的 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