使用Swagger自动构建API文档

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

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

Q:
什么是Swagger?

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

Swagger案列
本文的案例使用.net core3.0版本创建的webapi,具体的步骤如下:

1、创建webApi项目

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

2、配置项目

首先,下载安装两个nuget包:

安装Swashbuckle.AspNetCore,要注意版本的问题:

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

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

Microsoft.Extensions.PlatformAbstractions并不是

Swagger所必须的,只是为了获取目录文件所需。

编译时生成xml文档

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

3、编写核心代码

添加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.im/user/5cc30052e51d456e5b66adc2/activities")        }    });
    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,可对其进行测试

未经允许不得转载:大自然的搬运工 » 使用Swagger自动构建API文档

赞 (0)

评论 0

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址