.Net Core Swagger使用教程

什么是Swagger？

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

Swagger UI允许任何人（无论是您的开发团队还是最终用户）在没有任何实现逻辑的情况下可视化并与API的资源交互。它是根据您的OpenAPI（以前称为Swagger）规范自动生成的，可视化文档使后端实现和客户端使用更加容易。

.Net Core可以通过Nuget轻松安装Swagger组件，使用Swagger UI的强大功能，整个安装过程只需要1分钟，下面跟我来做吧。

Nuget搜索Swashbuckle.AspNetCore安装最新版本。

在Startup.cs里注册服务添加Swagger中间件，代码如下

public void ConfigureServices(IServiceCollection services)
{
    // 添加Swagger服务
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "WebApi Swagger", Version = "v1" });
    });
    services.AddControllers();
}
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    // 添加Swagger相关中间件
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "API Demo v1");
    });

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

到这里，已经安装完成了，直接按F5调试，然后打开http://localhost:{你的端口号}/swagger/index.html即可访问Swagger UI界面了。

我添加了一个示例控制器UserController，里面有Get，Post，Put，Delete四个Action，示例代码如下

namespace WebApiSwagger.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class UserController : ControllerBase
    {
        [HttpGet]
        public string Get(string name) {
            return $"My name is {name}";
        }
        [HttpPost]
        public string Post(string name) {
            return $"Add user {name}";
        }
        [HttpPut]
        public string Put(int id,string name) {
            return $"Update user set name as {name} where id is {id}";
        }
        [HttpDelete]
        public string Delete(string name) {
            return $"Delete {name}";
        }
    }
}

Swagger UI界面如下

如图所示，Swagger UI列出了我的接口信息。

点击某个接口可以查看接口的参数，如图所示，可以接收一个int类型的id和string类型的name参数。点击Try it out可以直接进行接口调用调试了，连PostMan都省了。

如果我们想知道每个方法的注释和方法参数的注释，这就需要对接口做XML注释了。首先安装Microsoft.Extensions.PlatformAbstractions包。

然后Startup.cs里Swagger服务增加一下配置

public void ConfigureServices(IServiceCollection services)
{
    // 添加Swagger服务
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "WebApi Swagger", Version = "v1" });
        // 获取xml文件名
        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        // 获取xml文件路径
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        // 添加控制器层注释，true表示显示控制器注释
        c.IncludeXmlComments(xmlPath, true);
    });
    services.AddControllers();
}

右键项目>属性，在生成菜单里勾选XML文档文件，勾选后，后面输入框里会自动显示xml地址，不需要做修改。如果不勾选直接运行会报错。

然后直接在接口中添加注释就可以了，还是以我UserController接口为例，我对Put方法做了如下修改，从body接收json格式的内容，输出Json。

[HttpPut]
public object Put([FromBody]UserRequest request) {
    return new
    {
        success = true,
        statusCode = 200,
        message = $"Update user set name as {request.Name} where id is {request.Id}"
    };
}
public class UserRequest { 
    /// <summary>
    /// 用户Id
    /// </summary>
    public int Id { get; set; }
    /// <summary>
    /// 用户姓名
    /// </summary>
    public string Name { get; set; }
}

运行效果如下，注释显示在接口地址后面了，Request也变成application/json类型了，点击Try it out可以修改Body内容进行调试了。

调试输出Json格式的结果

Swagger更多高级玩法欢迎大家补充。