Пользовательская группировка на конечных точках OpenAPI с Django Rest Framework

Question

У меня есть проект Django, и я использую Django REST framework. Я использую drf-Spectrum для представления OpenAPI, но я думаю, что моя проблема не связана с этим пакетом, мне это кажется более общим c 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 я получаю все конечные точки, сгруппированные под api endpoint , например: введите описание изображения здесь

Если добавить больше конечных точек под v1, все go под конечной точкой api .

Я хочу достичь конечных точек в Swagger сгруппированы по-разному, например, по приложению. Так что у меня было бы home , jwt , another_endpoint вместо api , так что в Swagger ( когда я добавляю больше конечных точек, текущий метод просто показывает массивный список URL-адресов, что не очень удобно для пользователя).

Я читал, что эти группы извлекаются из первого пути URL-адреса в В моем случае это api , поэтому, если я изменю структуру URL, я смогу достичь того, что мне нужно.

Но разве нет другого способа сделать это? Я хочу сохранить свою структуру URL-адресов и настроить ее отображение с помощью OpenAPI, поэтому в итоге у меня есть чванство, которое группирует конечные точки по приложениям, чтобы было легче ориентироваться и находить то, что вы ищете.

Answer 1

вы делаете это труднее, чем нужно. В глобальных настройках вы можете указать общее регулярное выражение префикса, которое удаляет ненужные части. это очистит для вас как operation_id, так и tags. В вашем случае это, вероятно, будет:

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

, что должно привести к тегам: home, jwt-auth, swagger. json, swagger.yaml

the tags on @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-Spectular вы можете использовать extension_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

Таким образом, вы должны использовать этот декоратор для расширения схемы в каждом представлении, которое вы хотите поместить в настраиваемую группу.