乐趣区

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

jiezi

本文包括两个部分：

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

WebApi 中使用 swagger

新建一个 webapi 项目

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

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

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


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

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

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

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

打开 valuescontroller，自己写一些注释

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


修改 webapi 的路由和默认参数

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

把 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 请求的参数也显示在文档里

退出移动版