以 swagger json 格式生成 WebAPI 文档答案

【问题标题】：Generate WebAPI documentation in swagger json format以 swagger json 格式生成 WebAPI 文档
【发布时间】：2014-02-15 16:08:17
【问题描述】：

我使用 .Net 4.5 创建了一个 WebAPI，并希望使用 Swagger 记录这个 API。我在我的 .Net 项目中添加了swagger-ui。现在，当我浏览到 ../swagger-ui/index.html 时，它会以 swagger UI 格式成功打开 pet store api-docs (json)。

我的问题是如何为我的 WebAPI 控制器和模型创建这样的 (swagger) json？正如我已将所需的 XML 摘要/cmets 放入 c# 类和属性中。

我看到Swagger.Net 和Swashbuckle 正在做类似的事情，但我真的不明白如何使用它们中的任何一个来生成 swagger-json 文件。我可能犯了一个很小的错误，但无法指出。

请帮忙。

【问题讨论】：

我想做与此相反的事情stackoverflow.com/questions/10560857/…
您找到问题的任何解决方案了吗？我也很感兴趣在不运行 Web 服务器的情况下生成 json 规范。
不，我还没有找到支持 WebAPI 属性路由的解决方案。

标签： json asp.net-web-api swagger api-doc

【解决方案1】：

您可以使用“NSwagStudio”桌面应用程序来加载 json 文档，而无需运行 api 项目。通过提供 api 程序集。

https://github.com/RSuter/NSwag/wiki/NSwagStudio

下载 (NSwagStudio) windows 桌面应用程序。

【讨论】：

【解决方案2】：

如前所述，/swagger 会将您带到 swagger UI。

如果您使用的是 Swashbuckle，那么 /swagger/docs/v1 应该会将您带到 swagger.json 文件 - 我是使用 Chrome 开发工具找到的。

编辑：如果您使用的是 Swashbuckle.AspNetCore，那么网址会略有不同 - /swagger/v1/swagger.json

【讨论】：

如果你使用的是 Swashbuckle。

【解决方案3】：

您需要将 Swagger.NET 集成到您的项目中，以便最终得到以下控制器：

public class SwaggerController : ApiController { /* snip */ }

您还应该注册以下路线：

context.Routes.MapHttpRoute (
name : "Swagger",
routeTemplate: "api/swagger"
defaults: new
{
  controller = "Swagger",
  action = "Get",
});

假设它正在工作，您应该能够调用 /api/swagger 并获得如下内容：

{
  apiVersion: "4.0.0.0",
  swaggerVersion: "2.0",
  basePath: "http://localhost:5555",
  resourcePath: null,
  apis: [
  {
    path: "/api/docs/Values",
    description: "No Documentation Found.",
    operations: [ ]
  },
  {
    path: "/api/docs/Home",
    description: "No Documentation Found.",
    operations: [ ]
  }
]

}

然后在 SwaggerUI/index.html 中你会想要更新 discoveryUrl:

<script type="text/javascript">
    $(function () {
        window.swaggerUi = new SwaggerUi({
            discoveryUrl: "http://localhost:5555/api/swagger",
            apiKey:"",
            dom_id:"swagger-ui-container",
            supportHeaderParams: false,
            supportedSubmitMethods: ['get', 'post', 'put']
        });

        window.swaggerUi.load();
    });
</script>

【讨论】：

这又是 doc 的运行时版本。我们必须运行一个网络服务器来获取/显示文档。但问题是关于如何生成 json 规范。我也对这个话题感兴趣——我需要在构建时生成一个 json Swagger 规范文件。
Swagger.Net 将使用 ASP.NET ApiExplorer 为您生成 json 规范。如果您出于某种原因需要保存 json 规范文件，则只需调用 url 并将结果保存到文件中。
某些数据将始终仅在运行时可用，这就是您需要运行该服务的原因。例如，路线将由代码定义，因此如果不运行服务，静态分析将无法猜测实际路线。