在Swagger JSON格式中生成WebAPI文档

Question

我使用 .Net 4.5 创建了一个 WebAPI，并希望使用 Swagger 对其进行文档化。 我已经在我的 .Net 项目中添加了 swagger-ui。现在，当我浏览到 ../swagger-ui/index.html 时，它成功地以 swagger UI 格式打开了 pet store api-docs（json）。

我的问题是如何为我的 WebAPI 控制器和模型创建这样的 (swagger) json？因为我已经在 c# 类和属性中添加了必要的 XML 摘要/注释。

我看到有 Swagger.Net 和 Swashbuckle 这些类似的工具正在做类似的事情，但我真的不知道如何使用它们中的任何一个生成 swagger-json 文件。可能是我犯了非常小的错误，但无法指出。

请帮帮我。

- theGeekster

---

我想做与这个相反的事情 https://dev59.com/tWkv5IYBdhLWcg3wfA0P - theGeekster

你找到问题的解决方案了吗？我也对在不运行Web服务器的情况下生成JSON规范很感兴趣。 - Shrike

不，我还没有找到任何支持WebAPI的Attribute Routing的解决方案。 - theGeekster

Answer 1

如上所述，/swagger会带您进入Swagger UI。

如果您正在使用Swashbuckle，则/swagger/docs/v1应该带您进入swagger.json文件 - 我使用Chrome Dev工具找到了此文件。

编辑：如果您正在使用Swashbuckle.AspNetCore，则URL稍有不同 - /swagger/v1/swagger.json

- Matt Frear

---

这是如果你正在使用Swashbuckle。 - Peter Marshall

Answer 2

您需要将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>

- Todd Smith

---

这是文档的运行时版本。我们必须运行一个Web服务器来获取/显示文档。但问题是如何生成JSON规范。我也对这个话题很感兴趣 - 我需要在构建时生成一个JSON Swagger规范文件。 - Shrike

Swagger.Net会使用ASP.NET ApiExplorer为您生成json规范。如果您出于某种原因需要保存json规范文件，只需调用URL并将结果保存到文件即可。 - Todd Smith

一些数据始终只能在运行时才可用，这就是为什么需要运行服务的原因。例如，路由将由代码定义，因此静态分析无法猜测实际路由而不运行服务。 - Sébastien Ros - MSFT

Answer 3

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

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

下载（NSwagStudio）Windows桌面应用程序。

- velmurugan