什么是Swagger？

• 本文已参与「新人创作礼」活动，一起开启掘金创作之路。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。通俗来说就是一个Api文档工具。NuGet包为 Swashbuckle.AspNetCore

Swagger他能做什么？

经历过传统开发的朋友应该深有感触，我记得我刚实习那一会儿，使用的是有道云，然后用Table的方式将Url,请求参数，返回参数一个一个填写到表格里面，每个字段的意思也要标注明白，再发给前端让前端再去对Api，如果出现改动还得去更新文档。
可想而知是非常耗费时间的，而且前端同事阅读起来也非常的不方便，使用Swagger能够将你代码注解直接展现，而且及时发布及时生效，对前后端分离项目非常友好。

Swagger有什么优点？

• 支持多语言
• 支持在线对接口进行调用测试
• 遵循OpenAPI 规范
• 接口文档在线生成
• 开源

如何在.NET Core项目中使用基础的Swagger

在Visual Studio中创建WebApi项目会默认在Proram中注入和引入Swagger中间件服务。但是提供的功能相对来说比较简单。我们可以自己动手来玩转Swagger。

上图是创建WebApi项目的时候默认生成的Swagger注入的服务，以及添加的中间件！

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "API标题",
        Description = "API描述"
    });
});

如上AddSwaggerGen使用了一个SwaggerGenOptions委托他提供了非常多的方法，如SwaggerDoc是为接口文档添加一些描述标注，但是这个时候你会发现我的Api没有描述如何让前端知道字段是什么意思？委托还提供了另外一个方法IncludeXmlComments 他主要是将项目生成的XML文件为接口提供了方法、参数、返回添加一些描述。

var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));

/// <summary>
/// 获取用户详情
/// </summary>
/// <param name="userId">用户编号</param>
/// <returns></returns>
[HttpGet("{userId}")]
public UserInfo GetUser(int userId)
{
    return new UserInfo();
}

/// <summary>
/// 用户信息
/// </summary>
public class UserInfo 
{
    /// <summary>
    /// 用户编号
    /// </summary>
    public int UserId { get; set; }
    /// <summary>
    /// 用户名称
    /// </summary>
    public string UserName { get; set; }
}

加上之后可以看到我们Api一些基础信息都展示出来了，确实非常的简单明了

使用Swagger为服务分组

比如在我们的商城管理系统中来说，我们用户是一个服务，订单也是一个服务，所有的API全放在一起，会让人非常疑惑。在我们 app.UseSwaggerUI 提供了一个委托。

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "用户服务",
        Description = "API描述"
    });
    options.SwaggerDoc("v2", new OpenApiInfo
    {
        Version = "v2",
        Title = "订单服务",
        Description = "API描述" 
    });
    var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
});

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "用户服务");
    c.SwaggerEndpoint("/swaggerv2/swagger.json", "订单服务");
});

给大家附图看效果，这里要注意的是分组展示需要在方法上面添加 ApiExplorerSettings 特性

/// <summary>
/// 获取订单详情
/// </summary>
/// <param name="orderId">订单编号</param>
/// <returns></returns>
[HttpGet("{orderId}")]
[ApiExplorerSettings(GroupName = "v2")]
public OrderInfo Get(int orderId) 
{
    return new OrderInfo();
}

更改 Swagger 的相对路径

默认情况下，Swagger UI 将显示在“/swagger”。如有必要，可以在 app.UseSwaggerUI中间件加入如下配置。

app.UseSwaggerUI(c =>
{
    c.RoutePrefix = "api"
}

总结

这里只为大家讲述了一些比较简单的用法，感兴趣的朋友也可以去查阅他的源码，还有很多功能没有讲述到，本文不做太多赘述，如：为Swagger添加自定CSS，为Swagger上锁（也就是授权访问Api）等等，可以根据项目需求，去查阅配置，非常简单。