ASP.NET Core-Swagger-公共和私有swagger页面

Question

我们有一个API，其中包含一些我们要公开公开的端点，还有一些我们不想公开的端点。但是我不只是想排除私有终结点，我仍然希望它们可见，而仅对某些用户或至少在不同的URL下可见。这似乎应该很普遍，但是我很难找出如何做到这一点。

目前，我们已经大摇大摆地设置并工作，显示了所有端点。某些控制器使用ApiExplorerSettings属性标记为“公共”组，如下所示（其中SwaggerGroups.Public是字符串常量“公共”）：

[ApiExplorerSettings(GroupName = SwaggerGroups.Public)]

理想情况下，我们将有一个醒目的页面显示所有标记为public的控制器/方法，而另一页面则显示所有端点的受密码保护的端点。这可能吗？

Answer 1

首先，您的问题听起来好像您没有正确地分隔API，实际上，它应该是两个api（微服务术语中的两个应用程序服务）。

同样，您也应该将其视为两个单独的API。

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("public", new OpenApiInfo { Title = "My Public API", Version = "v1" });
    c.SwaggerDoc("private", new OpenApiInfo { Title = "My Private API", Version = "v1" });
});

这将生成两个不同的OpenAPI（Swagger）规范。 /api-docs/public/swagger.json和/api-docs/private/swagger.json，可以在两个不同的UI应用程序中托管（一个受保护的其他公用应用程序）

// Public Docs Api
app.UseSwaggerUI(c =>
{
    // we use absolute uri here, since the swagger.json is outside of this application
    c.SwaggerEndpoint("http://example.com/api-docs/public/swagger.json", "Public API");
});


// Private Docs App
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("http://example.com/api-docs/private/swagger.json", "Private API");
});

一种替代方法是使用构建管道/连续集成系统。 Swashbuckle.AspNetCore在该库的5.x版本中提供了cli扩展，可以将其作为构建脚本的一部分执行，以在构建过程中生成swagger.json文件。

例如

dotnet swagger tofile --output ../swagger/myapi/private.json MyCompany.MyApplication.Mvc private
dotnet swagger tofile --output ../swagger/myapi/public.json MyCompany.MyApplication.Mvc public

并且有一个这样的文档应用程序

// Private Docs App
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("http://example.com/api-docs/swagger/myapp/private.json", "Private API");
    c.SwaggerEndpoint("http://example.com/api-docs/swagger/myapp/public.json", "Public API");
});

您使用Web服务器保护（nginx，apache，iis）的“ private.json”位置，即仅在内部网络中或在身份验证之后才允许private.json访问。

上述替代方法是将两个文件都托管在同一应用程序中，但使用中间件保护私有文件，请参见this GitHub issue以获取一些启发。