使用Swagger自动构建API文档随着前端技术不断的发展，如：webpack，vue，前端路由等出现，使得前后端分离在

前言

随着前端技术不断的发展，如：webpack，vue，前端路由等出现，使得前后端分离在项目中越来越普遍，后端工程师只需要完成API接口以及API接口文档。而编写API的规范和文档对于团队开发，测试变得越来越重要。因为，API文档是前后端对接的基本，但如果还停留在手写API文档的阶段，那就真的太 out 了。

本文将介绍如何使用Swagger工具，自动构建API文档。在学习之前，还是先了解一下Swagger的一些概念。

什么是Swagger？

Swagger 是一款RESTFUL接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。
支持为多种流行的语言，包括JavaScript、Python、Ruby、Java、Scala等。

Swagger案列演示

本文的案例使用.net core3.0版本创建的webapi，具体的步骤如下：

第一步、创建webApi项目

这里可以选择空模版，或者api模版，为了代码更简洁，这里选择Empty。

第二步、配置项目

首先，下载安装两个nuget包：

安装Swashbuckle.AspNetCore，要注意版本的问题：

如果你是.net core3.0及以上版本创建的项目，需要安装最新预发行版 5.0.0-rc5,千万不要安装最新稳定版，稳定版在.net core3.0及以上版本中会报错。

如果你是.net core3.0以下版本创建的项目，可安装稳定版。

Microsoft.Extensions.PlatformAbstractions并不是

Swagger所必须的，只是为了获取目录文件所需。编译时生成xml文档

启动页设置，你也可以不用设置，每次手动输入地址，但这里为了方便，设置一下，不用每次启动时，输入url地址了。

第三步、编写核心代码

添加swagger文档生成服务，需要注意.net core版本问题

//s.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });//.net core3.0之前版本使用这句
//.net core3.0之后版本使用下面一段
services.AddSwaggerGen(s =>
{
    s.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "My API",
        Version = "v1",
        Description = "Swagger演示",
        Contact = new OpenApiContact
        {
            Name = "吴同学",
            Email = "xxxxxxxx@qq.com",
            Url = new Uri("https://juejin.cn/user/2752832848532007")
        }
    });

    s.IncludeXmlComments(XmlCommentsFilePath);
});

获取接口注释文档


static string XmlCommentsFilePath
{
    get
    {
        var basePath = PlatformServices.Default.Application.ApplicationBasePath;
        var fileName = typeof(Startup).GetTypeInfo().Assembly.GetName().Name + ".xml";
        return System.IO.Path.Combine(basePath, fileName);
    }
}

添加最后的两个中间件配置，其余的代码Startup.cs自带

ModelRendering.Example意思Swagger UI页面的接口是显示Example，您也可以设置Model，如代码后面的图片

DocExpansion.None，意思把接口文档收起来，还有List，Full两个选项，看个人喜好，如果接口多收起来更好，如果少可以用List，或者Full

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

接着，添加一个控制器，随便加几个方法演示。

注意！！必须得有属性路由，也就是跟在HttpGet/HttpPost后面的地址


[Route("api/[controller]")]
[ApiController]
public class UsersController : ControllerBase
{
    private IUserService _uservice;
    public UsersController(IUserService uservice)
    {
        _uservice = uservice;
    }

    /// <summary>
    /// 测试接口
    /// </summary>
    /// <returns></returns>
    [HttpGet("test")]
    public ActionResult Test()
    {
        return Ok(new { ok = true, data = "成功" });
    }

    /// <summary>
    /// 根据用户ID，获取用户信息
    /// </summary>
    /// <param name="id">用户ID</param>
    /// <returns>用户信息</returns>
    [HttpGet("getId")]
    public ActionResult<string> GetId([FromHeader] string token,int id)
    {
        if (!"123456".Equals(token))
            return Ok(new { ok = false, data = "token错误" });
        else
            return $"你请求的 id 是 {id}";
    }

    /// <summary>
    /// 获取用户列表
    /// </summary>
    /// <returns></returns>
    [HttpGet("list")]
    public ActionResult GetList()
    {
        return Ok(new { ok = true, data = _uservice.GetList() });
    }

    /// <summary>
    /// 根据ID删除数据
    /// </summary>
    /// <param name="id">ID值</param>
    /// <returns></returns>
    [HttpPost("del/{id}")]
    public ActionResult<string> DelUserById(int id)
    {
        return $" id 是 {id}已被删除";
    }

    /// <summary>
    /// 新增用户
    /// </summary>
    /// <param name="token">token</param>
    /// <param name="u">用户信息</param>
    /// <returns></returns>
    [HttpPost("add")]
    public ActionResult AddUser([FromHeader] string token, [FromBody]Users u)
    {
            return Ok(new { ok = true, data = u.UName + "__" + u.UPassword });
    }
}

最后，启动webapi项目

点击展开api，可对其进行测试

好了，本次的分享就到这里，如果本文对你有帮助，欢迎点赞，将文章分享到朋友圈。
想要get到更多的开发知识，可以微信扫码关注公众号，每周会更新一两篇技术文章。