以swagger json格式生成WebAPI文档

时间:2014-01-24 15:34:18

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

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

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

我看到Swagger.NetSwashbuckle在做类似的事情,但我真的不明白如何使用其中任何一个生成swagger-json文件。我可能会犯很小的错误,但无法指出。

请帮忙。

3 个答案:

答案 0 :(得分:24)

如上所述,/ swagger带你进入招摇的UI。

如果你正在使用Swashbuckle,那么/swagger/docs/v1会带你到swagger.json文件 - 我发现这是使用Chrome Dev工具。

编辑:如果您使用的是Swashbuckle.AspNetCore,则网址略有不同 - /swagger/v1/swagger.json

答案 1 :(得分:4)

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

答案 2 :(得分:1)

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

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

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