使用 Django Rest 框架对 OpenAPI 端点进行自定义分组答案

【问题标题】：Custom Grouping on OpenAPI endpoints with Django Rest Framework使用 Django Rest 框架对 OpenAPI 端点进行自定义分组
【发布时间】：2020-07-10 08:25:36
【问题描述】：

我有一个 Django 项目，我正在使用 Django REST 框架。我正在使用drf-spectacular 对于 OpenAPI 表示，但我认为我的问题与这个包无关，对我来说这似乎是一个更通用的 OpenAPI 的东西（但不是 100% 确定我是否正确）。

假设我有这样的 URL 结构：

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include([
        path('v1/', include([
            path('auth/', include('rest_framework.urls', namespace='rest_framework')),
            path('jwt-auth/token/obtain', CustomTokenObtainPairView.as_view(), name='token_obtain_pair'),
            path('jwt-auth/token/refresh', CustomTokenRefreshView.as_view(), name='token_refresh'),
            path('home/', include("home.urls"))
        ]))
    ])),

    # OpenAPI endpoints
    path('swagger/', SpectacularSwaggerView.as_view(url_name='schema-swagger-json'), name='schema-swagger-ui'),
    path('swagger.yaml/', SpectacularAPIView.as_view(), name='schema-swagger-yaml'),
    path('swagger.json/', SpectacularJSONAPIView.as_view(), name='schema-swagger-json'),
    path('redoc/', SpectacularRedocView.as_view(url_name='schema-swagger-yaml'), name='schema-redoc'),
]

在相应的招摇 UI 视图中，我将所有端点分组在 api 端点下，例如：

如果在 v1 下添加更多的端点，都在 api 端点下。

我想要实现的是，让 Swagger 中的端点以不同的方式分组，例如通过应用程序。所以我会有 home、jwt、another_endpoint，而不仅仅是 api，这样会更容易在 Swagger 中导航（当我添加更多端点时，使用当前方法它只是显示大量 URL 列表，对用户不太友好）。

我读到这些组是从 URL 的第一个路径中提取的，在我的例子中是 api，所以如果我更改 URL 结构，我可以实现我需要的。

但是没有其他方法可以做到这一点吗？我想保留我的 URL 结构，并自定义如何使用 OpenAPI 显示它，所以最后我有一个按应用对端点进行分组的招摇，因此更容易导航和找到您要查找的内容。

【问题讨论】：

标签： django django-rest-framework swagger swagger-ui openapi

【解决方案1】：

你让它变得比它需要的更难。在全局设置中，您可以指定去除不需要的部分的通用前缀正则表达式。这将为您清理operation_id 和tags。在您的情况下，这可能是：

SPECTACULAR_SETTINGS = {
    'SCHEMA_PATH_PREFIX': r'/api/v[0-9]',
}

这应该会产生标签：home、jwt-auth、swagger.json、swagger.yaml

@extend_schema 上的 tags 只是为了方便在需要时偏离默认设置。每次操作都这样做会很麻烦。查看设置了解更多详情：

https://drf-spectacular.readthedocs.io/en/latest/settings.html

对于更精细的标记，您始终可以将AutoSchema 子类化并根据自己的喜好覆盖get_tags(self) 。干杯！

【讨论】：

【解决方案2】：

事实证明，您可以通过更改视图中的标签来控制这一点，按照 OpenAPI 规范：https://swagger.io/docs/specification/grouping-operations-with-tags/

因此，使用 drf-spectacular，您可以使用 extend_schema 装饰器来实现这一点，例如：

class CustomTokenObtainPairView(TokenObtainPairView):
    """
    Takes a set of user credentials and returns an access and refresh JSON web
    token pair to prove the authentication of those credentials.
    """
    @extend_schema(
        operation_id="jwt_obtain",
        ....
        tags=["aTestTag"]
    )
    def post(self, request, *args, **kwargs):
        # whatever

因此，您必须使用此装饰器来扩展要放入自定义组的每个视图中的架构。

【讨论】：