使用 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 中导航会更容易（当我添加更多端点时，使用当前方法它只是显示大量的 URL 列表，不是很用户友好） .

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

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

Answer 1

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

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

这应该导致标签：home、jwt-auth、swagger.json、swagger.yaml

在tags上@extend_schema仅仅是从默认的偏离在需要的地方提供了方便。每次操作都这样做会很麻烦。有关更多详细信息，请参阅设置：

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

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

Answer 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

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