Swagger to WebApi基于Swashbuckle构建RESTful风格文档

 本次和大家分享的是Swagger to WebApi的nuget包Swashbuckle;因为项目需要统一api文档的风格,并要支持多种开发语言(C#,java,python),所以首先想到的是swagger来构建api文档,本章讲解的是对.net的webpi来生成文档。

  • 准备工作
  • 快速构建简易api文档
  • swagger文档支持在header中增加Token参数

. 准备工作

  首先创webapi项目,然后通过nuget管理器安装Swashbuckle的包,我这里通过console命令安装:

   Install-Package Swashbuckle -Version 5.6.0

  注意只需要安装这个包就行了,其他的会自动引用,由于Swashbuckle包含了swagger的引用,所以不用再单独操作引用了。

. 快速构建简易api文档

  如上安装完Swashbuckle后其实就能够直接运行看效果了,我这里的访问路径是: http://localhost:51847/swagger/ui/index ,注意:/swagger/ui/index 是默认固定的路径,这是nuget包封装的路径,访问后能看到如下界面效果:

  使用Swashbuckle构建RESTful风格文档

  一个简易的文档就弄好了,swagger的颜色看起来搭配不错;由于大多数接口都是post请求方式,因此咋们以/api/values的post接口为例如:

  使用Swashbuckle构建RESTful风格文档

  对于接口文档而言,上面文档存在如下一些疏漏:

  • 未说明方法的功能
  • 参数属性的描述没有
  • 返回属性的描述没有

  为了方便其他人员对接接口,所以对接口文档我们需要增加一些描述,要增加描述这里就要知晓:Swashbuckle是通过xml文件来读取配置信息的,该xml文件里面包含了我们在代码中对方法,对类,对参数,对返回值做的文字描述;首先定义一个请求和响应的实体 如:

/// <summary>

/// 登录请求

/// </summary>

public class MoLoginRq

{

/// <summary>

/// 账号

/// </summary>

public string UserName { get; set; }

/// <summary>

/// 密码

/// </summary>

public string UserPwd { get; set; }

}

 

/// <summary>

/// 登录返回

/// </summary>

public class MoLoginRp

{

/// <summary>

/// 登录返回的token

/// </summary>

public string Token { get; set; }

}

 新增一个登录接口,代码如:

 

/// <summary>

/// 登录接口

/// </summary>

/// <param name=”rq”>请求</param>

/// <returns>响应</returns>

[HttpPost]

public MoLoginRp Login(MoLoginRq rq)

{

MoLoginRp rp = new MoLoginRp();

 

rp.Token = Guid.NewGuid().ToString();

 

return rp;

}

 

  到这里基本的动作都做完了,剩下的是上面我们说的xml文件怎么来,又怎么和swagger关联;

  首先,看项目的App_Start文件夹里面应该在安装nuget包的时候会自动增加一个 SwaggerConfig.cs 文件,里面就是swagger使用的一些设置,我们需要找到被注释的: //c.IncludeXmlComments(GetXmlCommentsPath()); 代码,取消注释并创建一个 GetXmlCommentsPath() 方法(获取xml注释文件路径) 如:

public static string GetXmlCommentsPath()

{

//D:/WebApplication/bin/WebApplication.xml

return Path.Combine(

AppDomain.CurrentDomain.BaseDirectory,

“bin”,

string.Format(“{0}.XML”, typeof(SwaggerConfig).Assembly.GetName().Name));

}

这个时候代码基本完成了,还需要我们通过vs设置一下生成项目时自动创建xml文件,如下:鼠标右键起始项目-》属性-》生成-》勾选xml文件

  使用Swashbuckle构建RESTful风格文档

  然后,鼠标右键重新生成下项目,这个时候bin目录就有了WebApplication.xml

  使用Swashbuckle构建RESTful风格文档

  这个xml文件内容就是一些注释的信息,具体各位自己点看看下xml内容;到这里我们设置和代码都弄完了,来看下swagger页面效果,通过预览 http://localhost:51847/swagger/ui/index :

  使用Swashbuckle构建RESTful风格文档

  这个时候我们增加的一些文字说明就完成了,这个时候细心的朋友能够看出来我们的Action方法名称没识别出来,这不符合我们命名规范,这里有两种解决方案:

  • 在action方法上增加 [ActionName(Login)] 标记
  • 修改WebApiConfig.cs文件的路由如:”api/{controller}/{action}/{id}”

  这里我采用后者,为了统一通过方法名来识别对应接口:

  使用Swashbuckle构建RESTful风格文档

swagger文档支持在header中增加Token参数

  对于api接口,我们通常在登录后的其他操作都会让调用方传递授权的token,而token一般做法是放在请求的header里面,swagger文档为了测试方便可以把token放在header作为参数传递;首先创建测试接口GetNames:

 

/// <summary>

/// 获取用户名称列表

/// </summary>

/// <returns></returns>

[HttpPost]

public List<string> GetNames()

{

List<string> list = new List<string> {“神牛001″,”神牛002”, “神牛003” };

 

return list;

}

然后在App_Start/SwaggerConfig.cs文件中添加:

 

1 c.ApiKey("apiKey")
2      .Description("授权token")
3      .Name("token")
4      .In("header");

  并启动:

1 EnableSwaggerUi(c =>
2      {     
3           c.EnableApiKeySupport("token", "header");
4     });

  然后启动并在swagger界面输入:

  使用Swashbuckle构建RESTful风格文档

  这个时候点击try it out请求接口,能够在看到请求里面包含了token信息:

  使用Swashbuckle构建RESTful风格文档


未经允许不得转载:996ICU » Swagger to WebApi基于Swashbuckle构建RESTful风格文档

赞 (0) 打赏