使用 Django Rest Framework 对 OpenAPI 端点进行自定义分组

Question

我有一个 Django 项目，并且正在使用 Django REST 框架。我正在使用drf-壮观 对于 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-spectaulous.readthedocs.io/en/latest/settings.html

对于更精细的标记，您可以随时根据自己的喜好对

AutoSchema

 进行子类化并覆盖 

get_tags(self)

。干杯！

Answer 2

事实证明，您可以根据 OpenAPI 规范通过更改视图中的标签来控制这一点：

https://swagger.io/docs/specation/grouping-operations-with-tags/

因此，对于 drf-spectaulous，您可以使用extend_schema 装饰器来实现此目的，例如：

from drf_spectacular.utils import 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 3

只需在视图上方使用此装饰器即可对端点进行分组：

@extend_schema(
 description='Store end point',
 tags=['Stores']
)
class Store(viewsets.ModelViewSet):
... rest of your code