.NET Core:API文档

  安装:Swashbuckle.AspNetCore
  启用 XML 注释:右键单击“解决方案资源管理器”中的项目,然后选择“属性”。勾选“生成”选项卡的“输出”部分下的“XML 文档文件”框。
  将 Swagger 生成器添加到 Startup.ConfigureServices 方法中的服务集合中:
  注册Swagger生成器,定义一个和多个Swagger 文档
services.AddSwaggerGen(c =>
{
     c.SwaggerDoc("v1", new Info { Title = "API", Version = "v1" });
     //加载注释文件
     var xmlPath = Path.Combine(AppInfo.BaseDirectory,  "***.xml");
     c.IncludeXmlComments(xmlPath);
     //启用数据注解
     c.EnableAnnotations();
});
  在 Startup.Configure 方法中,启用中间件为生成的 JSON 文档和 Swagger UI 提供服务:
app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
});
  需要注意的是使用该API文档功能时控制器的路由不能使用模板路由,而是要在控制器上面使用特性路由。
  启动应用,并导航到 http://localhost:<port>/swagger/index.html可以看到Api文档。
  默认情况下文档是不包含控制器注释的,需要另外添加。添加包:Swashbuckle.AspNetCore.Annotations
  在控制器上增加注解: [SwaggerTag("***")]
  分组的话可以在控制器上增加注解:[ApiExplorerSettings(GroupName = "***")]。然后在services.AddSwaggerGen和services.UseSwaggerUI时根据特性ApiExplorerSettings中的GroupName动态生成文档。
 
posted @ 2018-12-18 16:05 M守护神 阅读(...) 评论(...) 编辑 收藏