推荐一个接口文档自动生成工具Swagger

aqudgv 2019-07-01

本文包括两个部分:

  1. webapi中使用swagger
  2. 修改webapi的路由和默认参数

WebApi中使用swagger

新建一个webapi项目

推荐一个接口文档自动生成工具Swagger

项目打开之后,选择 引用,右键,管理NuGet程序包

推荐一个接口文档自动生成工具Swagger

浏览,搜索swagger,选择第一个swashbuckle,安装

推荐一个接口文档自动生成工具Swagger

安装好之后,右键项目,选择属性,生成,在下面的输出那里勾选:XML文档文件,如果没有自动填充好路径,需要自己填写一下,文件名可以自己取。

推荐一个接口文档自动生成工具Swagger
推荐一个接口文档自动生成工具Swagger

打开App_Start文件夹下的SwaggerConfig.cs文件,新增一个如下方法:

private static string GetXmlCommentsPath()
{
    return System.String.Format(@"{0}\bin\WebApiDemo.xml", System.AppDomain.CurrentDomain.BaseDirectory);
}

其中WebApiDemo.xml这个文件名要和自己在前一步填写的文件名一致

推荐一个接口文档自动生成工具Swagger

搜索GetXmlCommentsPath,下面能搜到已经注释了,自己把注释放开,要是没搜到,就自己手动写一下c.IncludeXmlComments(GetXmlCommentsPath());注意要写在register方法里面

推荐一个接口文档自动生成工具Swagger

打开valuescontroller,自己写一些注释

推荐一个接口文档自动生成工具Swagger

运行项目,在根路径后面直接加swagger,就会自动跳转到文档,如:http://localhost:8970/swagger,能看到我们写的一些注释

推荐一个接口文档自动生成工具Swagger
推荐一个接口文档自动生成工具Swagger

修改webapi的路由和默认参数

在实际应用中,完全使用webapi的restful风格的api设计是比较少见的,请求方式一般也只使用get请求和post请求,所以我们做一些修改,使用的是类似restful风格的api设计,修改一下webapi的路由配置

推荐一个接口文档自动生成工具Swagger

把valuescontroller做一些修改

/// <summary>
/// ValuesController的注释
/// </summary>
public class ValuesController : ApiController
{
    /// <summary>
    /// 获取列表
    /// </summary>
    /// <returns></returns>
    [HttpGet]
    public IEnumerable<string> GetList(int pageIndex, int pageSize, string search = "")
    {
        return new string[] { "value1", "value2" };
    }

    /// <summary>
    /// 设置键值对
    /// </summary>
    /// <param name="value"></param>
    [HttpPost]
    public string PostData([FromBody]string key, [FromBody]string value = "value")
    {
        return "{\"" + key + "\":\"" + value + "\"}";
    }

}

重新运行,能看到文档变成了如下,必填的参数显示required,非必填的参数可以不用填,post请求的参数也显示在文档里

推荐一个接口文档自动生成工具Swagger

相关推荐