以swagger json格式生成WebAPI文档

Question

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

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

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

请帮忙.

Answer 1

如上所述,/ swagger带您进入招摇UI.

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

编辑:如果你使用Swashbuckle.AspNetCore,那么网址略有不同 - /swagger/v1/swagger.json

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>