使用 Django Rest Framework 对 OpenAPI 端点进行自定义分组 [英] Custom Grouping on OpenAPI endpoints with Django Rest Framework

问题描述

我有一个 Django 项目，我正在使用 Django REST 框架.我正在使用

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

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

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

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

解决方案

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

I have a Django project and I am using Django REST framework. I am using drf-spectacular for OpenAPI representation, but I think my problem is not tied to this package, it's seems a more generic OpenAPI thing to me (but not 100% sure if I am right to this).

Assume that I have a URL structure like this:

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'),
]

In the corresponding swagger UI view, I get all endpoints grouped under api endpoint, e.g.:

If add more endpoints under v1, all go under the api endpoint.

What I want to achieve is, to have the endpoints in Swagger grouped differently, e.g. by app. So I'd have home, jwt, another_endpoint, instead of just api, so it will be easier to navigate in Swagger (when I add more endpoints, with the current method it's just showing a massive list of URLs, not very user friendly).

I've read that those groups are being extracted from the first path of a URL, in my case this is api, so if I change the URL structure, I could achieve what I need.

But isn't there another way of doing this? I want to keep my URL structure, and customize how I display this with OpenAPI, so in the end I have a swagger that groups the endpoints by app, so it's easier to navigate and find what you are looking for.

解决方案

you are making it harder than it needs to be. In the global settings you can specify a common prefix regex that strips the unwanted parts. that would clean up both operation_id and tags for you. In your case that would probably be:

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

that should result in tags: home, jwt-auth, swagger.json, swagger.yaml

the tags on @extend_schema is merely a convenience to deviate from the default where needed. it would be cumbersome to do this for every operation. see the settings for more details:

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

for even more elaborate tagging you can always subclass AutoSchema and override get_tags(self) to your liking. cheers!

这篇关于使用 Django Rest Framework 对 OpenAPI 端点进行自定义分组的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！