Swagger 为管理员和普通用户生成不同的文档答案

【问题标题】：Swagger Generate different documents for admin and regular usersSwagger 为管理员和普通用户生成不同的文档
【发布时间】：2017-06-21 22:15:01
【问题描述】：

我目前已将我的解决方案设置为为每个端点生成 Swagger 文档。但是，我有几个仅适用于管理员的端点。在下面，您将能够看到一个示例。

普通用户可以创建模型，但只有管理员可以提取数据库中的每个模型。

挑战是生成 2 套 swagger 文档？一个供普通用户查看，另一个文档供管理员用户查看。我知道，如果我将 [ApiExplorerSettings(IgnoreApi = true)] 添加到我的终点，它将不会出现在生成的文档中，但这意味着我的管理员用户也将无法看到该重要的文档。任何关于如何根据用户动态生成两组文档的建议都会有所帮助。

[SwaggerResponse((int)System.Net.HttpStatusCode.OK, Type = typeof(RestOkResponse<PackageResponse>))]
[SwaggerResponse((int)System.Net.HttpStatusCode.InternalServerError, Type = typeof(RestErrorResponse))]
[SwaggerResponse((int)System.Net.HttpStatusCode.BadRequest, Type = typeof(RestErrorResponse))]
[SwaggerResponse((int)System.Net.HttpStatusCode.Forbidden, Type = typeof(RestErrorResponse))]
[SwaggerResponse((int)System.Net.HttpStatusCode.NotFound)]
[HttpPost("/v1/packages")]
[Authorize()]
public async Task<IActionResult> CreateModel([FromBody]Request request)
{
    ...
}

以下方法仅供管理员使用：

[SwaggerResponse((int)System.Net.HttpStatusCode.OK, Type = typeof(RestOkResponse<PackageResponse>))]
[SwaggerResponse((int)System.Net.HttpStatusCode.InternalServerError, Type = typeof(RestErrorResponse))]
[SwaggerResponse((int)System.Net.HttpStatusCode.BadRequest, Type = typeof(RestErrorResponse))]
[SwaggerResponse((int)System.Net.HttpStatusCode.Forbidden, Type = typeof(RestErrorResponse))]
[SwaggerResponse((int)System.Net.HttpStatusCode.NotFound)]
[ApiExplorerSettings(IgnoreApi = true)]
[HttpPost("/v1/packages")]
[Authorize()]
public async Task<IActionResult> GetAllModelsFromDatabase([FromBody]Request request)
{
    ...
}

【问题讨论】：

标签： c# swagger

【解决方案1】：

在这个答案中发现了一个动态过程。

Dynamically Ignore WebAPI method on controller for api explorer documentation

可以分离 swagger 文档，但是没有内置方法可以做到这一点。必须从一个文档文件中删除不需要的节点： https://github.com/swagger-api/swagger-editor/issues/233

如果您自己托管编辑器，这在当前编辑器中可以正常工作 parameters_common.yaml 路径可以解析为 HTTP 路径。目前没有办法在文件之间跳转或创建一个新文件。如果您正在使用 Swagger 进行大型项目，我建议您托管自己编辑。当您正在构建的编辑器和 API 位于同源，XHR 调用不必是跨域的，这对编辑器有帮助显示有关“尝试操作”和您的 API 中调用的更多详细信息不必有跨域标头。

有关如何将 swagger 文件拆分为较小节点的示例。 http://azimi.me/2015/07/16/split-swagger-into-smaller-files.html

【讨论】：