ASP.NET Core WebApi使用Swagger生成api说明文档看这篇就够了

引言

为什么使用Swagger作为REST APIs文档生成工具

asp.net core中如何使用Swagger生成api说明文档呢

下面以Swashbuckle.AspNetCore为例为大家进行展示

Swashbuckle由哪些组成部分呢？

如何使用vs2017安装Swashbuckle呢？

添加并配置 Swagger 中间件

using Swashbuckle.AspNetCore.Swagger;

//注册Swagger生成器，定义一个和多个Swagger 文档
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
});

Startup.Configure

//启用中间件服务生成Swagger作为JSON终结点
app.UseSwagger();
//启用中间件服务对swagger-ui，指定Swagger JSON终结点
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});

http://localhost:<port>/swagger/v1/swagger.json

http://localhost:<port>/swagger

http://localhost:<port>/

RoutePrefix

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

Swagger的高级用法（自定义以及扩展）

使用Swagger为API文档增加说明信息

AddSwaggerGen

//注册Swagger生成器，定义一个和多个Swagger 文档
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info
{
Version = "v1",
Title = "yilezhu's API",
Description = "A simple example ASP.NET Core Web API",
TermsOfService = "None",
Contact = new Contact
{
Name = "依乐祝",
Email = string.Empty,
Url = "http://www.cnblogs.com/yilezhu/"
},
License = new License
{
Name = "许可证名字",
Url = "http://www.cnblogs.com/yilezhu/"
}
});
});

为接口方法添加注释

/// <summary>
/// 这是一个api方法的注释
/// </summary>
/// <returns></returns>
[HttpGet]
public ActionResult<IEnumerable<string>> Get()
{
return new string[] { "value1", "value2" };
}

启用XML 注释

warning CS1591: Missing XML comment for publicly visible type or member 'TodoController.GetAll()'

Path.GetDirectoryName(typeof(Program).Assembly.Location)

//注册Swagger生成器，定义一个和多个Swagger 文档
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info
{
Version = "v1",
Title = "yilezhu's API",
Description = "A simple example ASP.NET Core Web API",
TermsOfService = "None",
Contact = new Contact
{
Name = "依乐祝",
Email = string.Empty,
Url = "http://www.cnblogs.com/yilezhu/"
},
License = new License
{
Name = "许可证名字",
Url = "http://www.cnblogs.com/yilezhu/"
}
});
// 为 Swagger JSON and UI设置xml文档注释路径
var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//获取应用程序所在目录（绝对，不受工作目录影响，建议采用此方法获取路径）
var xmlPath = Path.Combine(basePath, "SwaggerDemo.xml");
c.IncludeXmlComments(xmlPath);
});

<summary>

Get

<summary>

<remarks>

/// <summary>
/// 这是一个带参数的get请求
/// </summary>
/// <remarks>
/// 例子:
/// Get api/Values/1
/// </remarks>
/// <param name="id">主键</param>
/// <returns>测试字符串</returns>
[HttpGet("{id}")]
public ActionResult<string> Get(int id)
{
return $"你请求的 id 是 {id}";
}

描述响应类型

/// <summary>
/// 这是一个带参数的get请求
/// </summary>
/// <remarks>
/// 例子:
/// Get api/Values/1
/// </remarks>
/// <param name="id">主键</param>
/// <returns>测试字符串</returns>
/// <response code="201">返回value字符串</response>
/// <response code="400">如果id为空</response>
// GET api/values/2
[HttpGet("{id}")]
[ProducesResponseType(201)]
[ProducesResponseType(400)]
public ActionResult<string> Get(int id)
{
return $"你请求的 id 是 {id}";
}

使用SwaggerUI测试api接口

总结