使用 Django Rest Framework 在 OpenAPI 端点上自定义分组

Question

我有一个 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'),
]

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

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

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

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

但是有没有其他方法可以做到这一点？我想保留我的 URL 结构，并自定义我如何使用 OpenAPI 显示它，所以最后我有一个大摇大摆的按应用程序对端点进行分组，这样更容易导航和找到你正在寻找的东西。

Answer 1

事实证明，您可以根据 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

所以你必须使用这个装饰器来扩展你想要放入自定义组的每个视图中的架构。

Answer 2

你让它变得比需要的更难。在全局设置中，您可以指定一个公共前缀正则表达式来去除不需要的部分。这将为您清理 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) 。干杯！

使用 Django Rest Framework 在 OpenAPI 端点上自定义分组

Custom Grouping on OpenAPI endpoints with Django Rest Framework

django

swagger

django-rest-framework

swagger-ui

openapi