Django 自定义分组 OpenAPI 端点与 Django Rest Framework

在本文中，我们将介绍如何使用 Django Rest Framework（DRF）在 OpenAPI 端点上进行自定义分组。OpenAPI（旧称Swagger）是一个用于定义和描述 RESTful APIs 的规范，而 DRF 是一个为 Django 应用程序提供强大的 RESTful API 框架。

阅读更多：Django 教程

什么是 OpenAPI？

OpenAPI 是一个以 JSON 或 YAML 格式编写的 API 规范。它用于定义 API 的请求和响应的结构、参数、路由等信息。OpenAPI 可以通过自动生成文档和代码来方便地创建、管理和测试 APIs。

什么是 Django Rest Framework？

Django Rest Framework 是一个基于 Django 的用于构建 RESTful APIs 的强大框架。它提供了许多功能，包括序列化、视图、认证、权限控制、版本控制、响应内容协商等。DRF 还与许多其他的第三方库和工具集成得非常好，使得构建和管理 API 变得非常简单和高效。

自定义分组 OpenAPI 端点

在 DRF 中，我们可以使用 @swagger_auto_schema 装饰器来自定义 OpenAPI 端点的属性。该装饰器允许我们添加自定义的元数据，例如端点的描述、请求和响应的结构、参数的详细信息等。

首先，我们需要在 Django 项目的 urls.py 文件中导入 swagger_auto_schema ：

from drf_yasg import openapi
from drf_yasg.views import get_schema_view
from drf_yasg.inspectors import SwaggerAutoSchema

schema_view = get_schema_view(
    openapi.Info(
        title="My API",
        default_version='v1',
        description="My API description",
    ),
    public=True,
    permission_classes=[permissions.AllowAny],
    inspector=SwaggerAutoSchema,
)

然后，我们可以使用 @swagger_auto_schema 装饰器来自定义某个 API 端点的属性。以下是一个示例：

from drf_yasg.utils import swagger_auto_schema

@swagger_auto_schema(
    operation_description="This API endpoint retrieves a list of users.",
    operation_summary="Get list of users",
    responses={
        200: "Success",
        400: "Bad request",
        404: "Not found",
    },
)
@api_view(['GET'])
def user_list(request):
    """
    API endpoint to retrieve a list of users.
    """
    users = User.objects.all()
    serializer = UserSerializer(users, many=True)
    return Response(serializer.data)

在上面的示例中，我们使用了 @swagger_auto_schema 装饰器来为 user_list 视图添加了一些元数据。这些元数据包括了操作的描述信息、操作的摘要信息以及可能的响应状态。

自定义分组示例

除了自定义端点的属性，我们还可以使用 DRF 提供的 SchemaGenerator 类进行自定义分组。我们可以根据需要将端点分组并显示在 OpenAPI 文档中。

首先，我们需要在 Django 项目的 settings.py 文件中配置生成 OpenAPI 文档所需的信息：

SWAGGER_SETTINGS = {
    'DEFAULT_INFO': 'path.to.info_func',
    'DEFAULT_GENERATOR_CLASS': 'path.to.generator_class',
    'DEFAULT_MODEL_INCLUDE_KEYS': ['include_keys'],
}

然后，我们需要创建一个自定义的 SchemaGenerator 类。以下是一个示例：

from drf_yasg import openapi
from drf_yasg.inspectors import SwaggerAutoSchema
from drf_yasg.generators import OpenAPISchemaGenerator

class CustomSchemaGenerator(OpenAPISchemaGenerator):
    def get_info(self):
        return openapi.Info(  # 定义信息
            title='My API',
            default_version='v1',
            description='My API description',
        )

    def get_tags(self, request):
        return [  # 自定义标签
            openapi.Tag(name='Users', description='User endpoints'),
            openapi.Tag(name='Products', description='Product endpoints'),
        ]

    def determine_paths(self):
        # 自定义路径
        paths = {
            '/users/': self._generate_user_paths(),
            '/products/': self._generate_product_paths(),
        }
        return paths

    def _generate_user_paths(self):
        # 生成用户路径
        paths = {
            'get': SwaggerAutoSchema(
                tags=['Users'],  # 将路径与标签相关联
                operation_description='This endpoint retrieves a list of users.',
            ),
            'post': SwaggerAutoSchema(
                tags=['Users'],
                operation_description='This endpoint creates a new user.',
            ),
        }
        return paths

    def _generate_product_paths(self):
        # 生成产品路径
        paths = {
            'get': SwaggerAutoSchema(
                tags=['Products'],
                operation_description='This endpoint retrieves a list of products.',
            ),
            'post': SwaggerAutoSchema(
                tags=['Products'],
                operation_description='This endpoint creates a new product.',
            ),
        }
        return paths

最后，我们需要在 Django 项目的 urls.py 文件中使用自定义的 SchemaGenerator 类：

from drf_yasg.views import get_schema_view

schema_view = get_schema_view(
    generator_class=CustomSchemaGenerator,
)

urlpatterns = [
    # ...
    path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='swagger'),
    # ...
]

在上面的示例中，我们自定义了 SchemaGenerator 类，指定了 API 的标签、路径、操作的描述等信息。这样，OpenAPI 文档中的端点就按照我们的分组进行显示了。