使用Swashbuckle.AspNetCore.SwaggerGen 生成 ASP.NET Core2 WebAPI 在线文档

目录

Swagger的作用

怎么生成API文档

怎么生成文档中的注释说明？

文档中去调用API

隐藏想隐藏的API

接口分组

---

Swagger的作用

在我们开发WebAPI 时 通常需要为调用我们API的客户端提供说明文档。Swager 就是这样的一个 工具，它能生成漂亮的API文档和提供在线调用的页面。

 

Swashbuckle.AspNetCore 中分为3个组件，我们可以使用其中一个或多个。

Package	Description
Swashbuckle.AspNetCore.Swagger	Exposes SwaggerDocument objects as a JSON API. It expects an implementation of ISwaggerProvider to be registered which it queries to retrieve Swagger document(s) before returning as serialized JSON
Swashbuckle.AspNetCore.SwaggerGen	Injects an implementation of ISwaggerProvider that can be used by the above component. This particular implementation automatically generates SwaggerDocument(s) from your routes, controllers and models
Swashbuckle.AspNetCore.SwaggerUI	Exposes an embedded version of the swagger-ui. You specify the API endpoints where it can obtain Swagger JSON and it uses them to power interactive docs for your API

 

本文使用Swashbuckle.AspNetCore.SwaggerGen 3.0 版本来生成API文档。

怎么生成API文档

1. 使用NuGet 添加引用"Swashbuckle.AspNetCore.SwaggerGen"到项目，这里我们选择SwaggerGen是因为它里面包含了DataAnnotations 后面我们会用到。

2. 在 Startup.cs 中的ConfigureServices 方法中注册SwaggerGen

services.AddMvc();

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
});

3. 添加API方法，这我们添加2个API，Users和Roles， 后面我们访问swagger 将会显示这2个API的接口

    [Produces("application/json")]
    [Route("api/user/[controller]")]
    public class UserController : Controller
    {
        /// 

        /// 用户创建接口
        /// 
        /// 
        [HttpPost]
        public void Create([FromBody]User user) {
            //Todo: 创建用户处理
        }
        /// 

        /// 用户关键字搜索
        /// 
        /// 
        [HttpGet]
        public void Search(string keyword)
        {
            //TODO: 查询业务
        }
    }

 

    [Produces("application/json")]
    [Route("api/role/[controller]")]
    public class RoleController : Controller
    {
        /// 

        /// 角色添加
        /// 
        [HttpPost]
        public void Create()
        {
            //TODO: 添加角色业务
        }
        /// 

        /// 角色检索
        /// 
        /// 
        [HttpGet]
        public void Search(string keyword)
        {
            //TODO: 查询业务
        }
    }

4. 在 Configure 方法中启用启用Swagger中间件，并制定从哪个JSON中显示文档。

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});

注意这里的"/swagger/v1/swagger.json" 中的v1 必须和services.AddSwaggerGen 中的v1 对应，否则ui中将找不到对于的json文件。

这时候我们启动 API 服务 访问/swagger 就将显示 我们公布的API文档了。

怎么生成文档中的注释说明？

     这里的文档并没有注释说明接口具体是干什么的，怎么把我们代码中的注释显示出来呢？

1. API 项目属性->生成：输出 勾选"XML文档文件"

2. 代码中 ConfigureServices  方法中指定xml文档路径

services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
                var filePath = Path.Combine(System.AppContext.BaseDirectory, "SwaggeruiDemo.xml");
                c.IncludeXmlComments(filePath);
            });

再浏览/swagger 就显示了 注释。

 

文档中去调用API

    我们的WebAPI 文档已经完美了，但API服务并不能工作，直接请求API将会404，因为目前我们的MVC还未启动路由发现。我们需要使用启动MVC的路由

1. 在 ConfigureServices 方法中，添加AddApiExplorer

services.AddMvcCore().AddApiExplorer();

2. 在 Configure 中添加一个路由

app.UseMvc(routes =>
{
   routes.MapRoute("default", "{controller=Home}/{action=Index}/{id?}");
});

这时我们的 API服务就能正常工作，Swagger 文档也能完美使用。

 

待续：

隐藏想隐藏的API

1. 我们在使用中有的API 可能不希望暴露在文档中，怎么设置呢？

  [Produces("application/json")]
    [Route("api/values")]
    public class ValueController : Controller
    {
        [ApiExplorerSettings(IgnoreApi = true)]
        [HttpGet]
        public string Value (){
            return "Value";
        }
    }

在需要隐藏的方法上面加上  [ApiExplorerSettings(IgnoreApi = true)]     

接口按Tags分组