Django drf-spectacular 如何拆分 api 描述以供公共(public)和私有(private)使用？

Question

我想制作 2 个不同的文档。一个是面向公众的，只有很少的 api 方法并且没有 authz。另一个用于所有 api 方法的私有(private)使用，并且仅供授权用户使用。

Answer 1

2个选择:

1. 如果您使用内置的 Swagger，并且访问 UI 的用户以某种方式被授权，您可以使用设置 'SERVE_PUBLIC': False。它将根据请求用户有权访问的权限过滤架构。 Spectacular 将尝试使用 Authorize 按钮提供的(第一个)凭据并使用它获取模式。如果您的身份验证方法不同于 DRF 的设置 AUTHENTICATION_CLASSES，您可能还需要相应地设置 spectacular 的 SERVE_AUTHENTICATION。

2. 或者实际创建 2(+2) 个服务于不同模式的端点并可能自定义它们

# public part
path('api/schema/swagger-ui-public/', SpectacularSwaggerView.as_view(
    custom_settings={
        'SERVE_URLCONF': [...] # urlpatterns with the public endpoint list
    },
    url_name='schema-public')
),
path('api/schema-public/', SpectacularAPIView.as_view(), name='schema-public'),
    
# private part
path('api/schema-private/', SpectacularAPIView.as_view(
      # settings deviating from global spectacular settings go here.
      custom_settings={
          'TITLE': 'Private API',
          'SERVE_URLCONF': [...] # urlpatterns with the private endpoint list
          ...
      },
      # not required but might want to also protect if it is sensitive
      authentication_classes=[...],
      permission_classes=[...],
  ), name='schema-private'
),
path('api/schema/swagger-ui-private/', SpectacularSwaggerView.as_view(url_name='schema-private')),