Django：使用drf_yasg生成Swagger API文档

今天啥也没干
2,025 阅读2分钟

摘要：本文将介绍drf_yasg库，它是如何使用Swagger生成API文档的，以及如何安装和配置drf_yasg。我们还将通过实例代码演示如何使用装饰器生成API文档。

  1. 什么是drf_yasg？

drf_yasg（Django REST framework Yet Another Swagger Generator）是一个用于Django REST framework的第三方库，它可以帮助我们自动生成API文档。通过使用drf_yasg，我们可以轻松地为我们的API生成易于阅读和理解的文档，从而提高开发效率和协作效果。

  1. 什么是Swagger？

Swagger是一个用于设计、构建和记录RESTful API的开源框架。它可以帮助我们生成易于阅读和理解的API文档，从而提高开发效率和协作效果。Swagger的核心组件是Swagger UI，它是一个可视化的API文档查看和测试工具。

  1. drf_yasg如何使用Swagger来生成API文档？

drf_yasg通过分析Django REST framework中的视图和序列化器，自动生成Swagger规范的JSON或YAML文件。然后，这些文件可以被Swagger UI解析，生成可视化的API文档。

  1. 安装和配置drf_yasg

4.1 安装drf_yasg

要安装drf_yasg，只需使用pip命令：

复制
pip install drf-yasg

4.2 配置drf_yasg

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

python复制
INSTALLED_APPS = [
    # ...
    'drf_yasg',
]

4.3 配置Swagger UI

在项目的urls.py文件中，导入drf_yasg库，并配置Swagger UI的URL：

python复制
from django.urls import path, re_path
from drf_yasg.views import get_schema_view
from drf_yasg import openapi

schema_view = get_schema_view(
    openapi.Info(
        title="My API",
        default_version='v1',
        description="My API description",
    ),
    public=True,
)

urlpatterns = [
    # ...
    re_path(r'^swagger/$', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
]
  1. 使用drf_yasg生成API文档

5.1 使用装饰器（api_view，swagger_auto_schema）生成文档

在视图函数中，我们可以使用drf_yasg提供的装饰器来自定义API文档。例如：

python复制
from rest_framework.decorators import api_view
from drf_yasg.utils import swagger_auto_schema
from drf_yasg import openapi

@api_view(['GET'])
@swagger_auto_schema(
    operation_description="获取所有用户",
    responses={
        200: openapi.Response("请求成功", schema=openapi.Schema(type=openapi.TYPE_ARRAY, items=openapi.Schema(type=openapi.TYPE_OBJECT))),
        400: "请求失败",
    },
)
def get_users(request):
    # ...

这样，我们就可以为get_users视图函数生成自定义的API文档。

总结：本文介绍了drf_yasg库，它是如何使用Swagger生成API文档的，以及如何安装和配置drf_yasg。我们还通过实例代码演示了如何使用装饰器生成API文档。希望本文能帮助你更好地理解和使用drf_yasg。

avatar
文章
阅读
粉丝