从 Django REST Swagger 中排除 URL

Posted 2023-02-19

【中文标题】从 Django REST Swagger 中排除 URL

【英文标题】：Exclude URLs from Django REST Swagger

【发布时间】：2014-06-09 10:20:57

【问题描述】：

我想从我的 REST API 文档中排除一些 URL。我正在使用 Django REST Swagger，而我能找到的唯一文档 (https://github.com/marcgibbons/django-rest-swagger) 并没有真正告诉我太多。 settings.py 中有 SWAGGER_SETTINGS 的“exclude_namespaces”部分，但没有真正的解释或示例说明如何使用它。

简单地说，我想从文档中排除以以下内容开头的所有 URL：

/api/jobs/status/
/api/jobs/parameters/

我该怎么做呢？

提前感谢您提供的任何帮助：P

【问题讨论】：

关于排除特定端点的特定 HTTP 方法，我有一个有点相关但更细粒度的问题：***.com/questions/52813253/…

【参考方案1】：

要排除的命名空间是您的 urls.py 中定义的命名空间。

例如，在您的情况下：

urls.py:

internal_apis = patterns('',
                     url(r'^/api/jobs/status/',...),
                     url(r'^/api/jobs/parameters/',...),
                     )

urlpatterns = urlpatterns + patterns('',
              url(r'^', include(internal_apis, namespace="internal_apis")),
              ...
              )

在你的 settings.py 中：

SWAGGER_SETTINGS = 
    "exclude_namespaces": ["internal_apis"],    #  List URL namespaces to ignore

这很好描述in there

【讨论】：

这在最新版本的 django 中不再有效

【参考方案2】：

对于所有认为上述答案没有帮助的人： 我猜“exclude_namespaces”在新版本的 django swagger 中不再起作用。我遇到了几乎相同的问题（我不想在文档中显示我的内部 API），并且上述解决方案对我不起作用。我一直在寻找一个小时的解决方案，终于找到了一些有用的东西。

您可以将一些属性传递给 SchemaGenerator。其中之一是 urlconf。您可以将其设置为“yourproject.api.urls”，它只会获取那里定义的 url！当然，您必须确保您想要从 api 文档中排除的所有 url 都不包含在其中。

我希望至少有一个人觉得我的回答有帮助；）。

当您希望在您的 api 文档中包含许多 urls.py 时，就会出现问题。我不知道那时应该怎么做。如果有人想出这个新问题的答案 - 请随时评论我的答案。谢谢！

【讨论】：

您还可以通过将schema = None 添加到其属性来禁用特定视图。

【参考方案3】：

对于最新版本的 drf-swagger，您可以在架构生成器中污染 url 模式。

例如： url_patterns = ( url(r'^api/v1/', include(router.urls, namespace='api')), ) generator = schemas.SchemaGenerator(title='Core API', patterns=url_patterns)

【参考方案4】：

奥拉的回答是正确的。 exclude_namespaces 不再受支持。

为了更好地控制文档，请使用基于函数或基于类的视图创建您自己的模式视图。如果您想为特定的 URL 模式或 URL 配置生成文档，这将很有用。

在您的views.py 中，您可以执行以下操作：

from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework.schemas import SchemaGenerator
from rest_framework_swagger import renderers

class SwaggerSchemaView(APIView):
    renderer_classes = [
        renderers.OpenAPIRenderer,
        renderers.SwaggerUIRenderer
    ]

    def get(self, request):
        generator = SchemaGenerator(title='Your API Documentation', urlconf='your_app.urls')
        schema = generator.get_schema(request=request)

    return Response(schema)

以上将只呈现在SchemaGenerator 的urlconf 参数中指定的URL 的文档。另外，不要忘记设置您的urls.py：

from django.conf.urls import url
from views import SwaggerSchemaView

urlpatterns = [
    url(r'^api/v1/docs/$', SwaggerSchemaView.as_view(), name='docs'),
]

【讨论】：

这个答案似乎可以很好地解决我遇到的问题，但我不确定urlconf='your_app.urls' 是什么意思 - 请您介意扩展一下吗？

@knirirr 它是 urls.py 文件的路径，对应于您要为其生成 Swagger Schema 视图的任何 URL。这有帮助吗？

谢谢。所有 API URL 都在一个主 urls.py 文件中，但我只需要在 Swagger 文档中显示其中的一些。如果 Django 可以处理两个文件，那么我大概可以将那些实际上要记录的文件放在一个单独的文件中，而将私有文件留在主 URL 文件中。

这几乎就是我所做的，只是我为私有文件创建了一个新的 urls.py 文件。

【参考方案5】：

使用新版本的 django swagger，我们不需要创建视图来排除某些 url。下面的代码将禁用 test2 url。

from rest_framework_swagger.views import get_swagger_view
urlpatterns1 = [
    url(r'^', include(router.urls)),
    url(r'^test/', include('test.urls')),
    url(r'^test1/', Test2.as_view()),
]

schema_view = get_swagger_view(title='API Documentation', patterns=urlpatterns1)

urlpatterns = urlpatterns1 + [
    url(r'^docs/', schema_view),
    url(r'^test2/', Test2.as_view()),
]

【参考方案6】：

更灵活的解决方案是：

from django.contrib import admin
from django.urls import include, path
from rest_framework_swagger.views import get_swagger_view
urlpatterns = [
    path('admin/', admin.site.urls),
    path('users/', include('user.urls', namespace="user")),
    path('locations/', include('location.urls')),
    path('departments/', include('department.urls', namespace="department")),
    path('my_secret_api/', include('secret.urls', namespace="secret_api")),
]

to_exclude = ['secret_api',] # some more namespaces here
swagger_urls = [item for item in urlpatterns if hasattr(item,"namespace") and item.namespace not in to_exclude]
schema_view = get_swagger_view(title='Highky', patterns=swagger_urls)
urlpatterns += [
        path('api/docs/', schema_view),
]

urlpatterns 将具有所有五个路径，但 swagger_urls 将具有四个路径，不包括 secret_api。

您的所有 URL 和包含将继续按原样工作，除了我们现在传递我们希望在 Swagger 文档中显示的修改后的 urlpatterns。检查还将涵盖您未指定命名空间的包含（如在我们的示例中，命名空间未在位置中定义）。

【参考方案7】：

views.py

任何视图类

class ...ViewSet(viewsets.ModelViewSet):
    queryset = ....objects.all().order_by('-id')
    serializer_class = ...Serializer
    http_method_names = ['get', 'post', 'patch', 'delete'] # add or exclude

任何基于函数的视图

@api_view(['get']) # target field
def function(request):
    ...
    return Response(...)