Web Api 2.0中使用Swagger生成Api文档的2个小Tips
当Web Api 2.0使用OAuth2授权时,如何在Swagger中添加Authorization请求头?
Swagger说明文档支持手动调用Api, 但是当Api使用OAuth2授权时,由于没有地方可以输入授权Token, 导致响应结果一直是401没有授权。
解决方案:
在Swagger配置文件中,添加对请求头中Authorization的设置。
1. 在Api项目中添加一个新类AddAuthorizationHeader并实现IOperationFilter接口
public class AddAuthorizationHeader : IOperationFilter
{
/// <summary>
/// Adds an authorization header to the given operation in Swagger.
/// </summary>
/// <param name="operation">The Swashbuckle operation.</param>
/// <param name="schemaRegistry">The Swashbuckle schema registry.</param>
/// <param name="apiDescription">The Swashbuckle api description.</param>
public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
{
if (operation == null) return; if (operation.parameters == null)
{
operation.parameters = new List<Parameter>(); } var parameter = new Parameter
{
description = "Token",
@in = "header",
name = "Authorization",
required = true,
type = "string"
}; if (apiDescription.ActionDescriptor.GetCustomAttributes<AllowAnonymousAttribute>().Any())
{
//如果Api方法是允许匿名方法,Token不是必填的 parameter.required = false;
} operation.parameters.Add(parameter);
}
}
2. 在SwaggerConfig.cs中启用Authorization请求头。
public static void Register(HttpConfiguration config)
{
var thisAssembly = typeof(SwaggerConfig).Assembly; config.EnableSwagger(c =>
{ c.OperationFilter<AddAuthorizationHeader>(); c.SingleApiVersion("v1", "EHealthCareClinic.WebApi"); c.IncludeXmlComments(GetXmlCommentsPath());
})
.EnableSwaggerUi(c =>
{
});
}
3. 编译Api项目,重新打开Swagger说明文档, Parameters列表中就会出现Authorization变量,录入正确的授权Token, 401未授权问题消失。
当Web Api 2.0使用IHttpActionResult作为返回值时,如何在Swagger中生成Response Class范例?
IHttpActionResult是Web Api 2.0引入的接口。
使用IHttpActionResult作为Api 返回值的好处。
- 简化对控制器的单元测试
- 创建Http响应的通用逻辑被移动到单独的类中
- 通过隐藏构建相应的底层细节,使控制器动作更清晰
Swagger生成文档的原理是通过读取Web Api项目生成的XML文档说明文件,使用反射技术,动态展示每个Action方法的方法签名。
但是当使用IHttpActionResult作为Api方法返回值之后,Swagger不能通过反射正确读取到返回值的类型,所以导致生成的文档缺少。
例:
/// <summary>
/// 获取省份列表
/// <param name="countryId">国家ID</param>
/// </summary>
[HttpGet]
[Route("countries/{countryId}/provinces")]
public IHttpActionResult GetProvinceList(Guid countryId)
{
var result = QueryService.GetProvinceCollection(new CountryId(countryId));
return Ok(result);
}
解决方案:
Web Api 2.0中引入了一个新的特性类System.Web.Http.Description.ResponseTypeAttribute。
这个特性类构造只有一个参数,即返回值的类型。
我们只需要在每个Api方法签名处使用这个新特性声明Api返回值的类型, Swagger生成的说明文档中就会出现返回类型的说明。
/// <summary>
/// 获取省份列表
/// <param name="countryId">国家ID</param>
/// </summary>
[HttpGet]
[Route("countries/{countryId}/provinces")]
[ResponseType(typeof(IEnumerable<EHealthCareClinic.Business.QueryModel.ProvincePresentation>))]
public IHttpActionResult GetProvinceList(Guid countryId)
{
var result = QueryService.GetProvinceCollection(new CountryId(countryId));
return Ok(result);
}
Web Api 2.0中使用Swagger生成Api文档的2个小Tips的更多相关文章
- NetCore 3.0 中使用Swagger生成Api说明文档及升级报错原因
认识Swagger Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新.文件的方法,参 ...
- asp.net core 使用 swagger 生成接口文档
参考地址:http://www.cnblogs.com/daxnet/p/6181366.html http://www.jianshu.com/p/fa5a9b76f3ed 微软参考文档:https ...
- .net core 使用 swagger 生成接口文档
微软参考文档:https://docs.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger?tabs= ...
- ASP.NET Core 3.0 WebApi中使用Swagger生成API文档简介
参考地址,官网:https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-swashbuckle?view ...
- ASP.NET WebAPI使用Swagger生成测试文档
ASP.NET WebAPI使用Swagger生成测试文档 SwaggerUI是一个简单的Restful API测试和文档工具.简单.漂亮.易用(官方demo).通过读取JSON配置显示API .项目 ...
- PCB DotNetCore Swagger生成WebAPI文档配置方法
在.net framework框架下可以使用WebApiTestClientWebApi生成WebAPI接口文档与方便接口测试用,而在DotnetCore却没有找到这个工具了,baidu查找一下发现有 ...
- SpringBoot2中,怎么生成静态文档
SpringBoot2中,怎么生成静态文档 在实际开发过程中,我们通过swagger就可以生成我们的接口文档,这个文档就可以提供给前端人员开发使用的.但是,有时候,我们需要把我们的接口文档,提供给第三 ...
- webapi 利用webapiHelp和swagger生成接口文档
webapi 利用webapiHelp和swagger生成接口文档.均依赖xml(需允许项目生成注释xml) webapiHelp:微软技术自带,仅含有模块.方法.请求-相应参数的注释. swagge ...
- Java Web项目中使用Freemarker生成Word文档
Web项目中生成Word文档的操作屡见不鲜.基于Java的解决方式也是非常多的,包含使用Jacob.Apache POI.Java2Word.iText等各种方式,事实上在从Office 2003開始 ...
随机推荐
- (MariaDB)MySQL数据类型详解和存储机制
html { font-family: sans-serif } body { margin: 0 } article,aside,details,figcaption,figure,footer,h ...
- Java 从键盘输入
package io; import java.io.*; public class ReadAndWrite { public static void main(String[] args) { I ...
- javascript 之作用域链-07
复习作用域 上一节我们说到作用域:是指变量可以访问的范围,他规定了如何查找变量,以及确定当前执行代码对变量的访问权限:也说到静态作用域即词法作用域,是在编译阶段决定变量的引用(由程序定义的位置决定,和 ...
- android开发第一天
今天可以说是我正式投入android怀抱的第一天吧,按着自己的兴趣,努力地吸取知识.听了程老师的课,也觉得收获很多,毕竟以前都是看着书本或者网页教程来学习,第一次有人这么直接地跟你教授着,说着一些你听 ...
- javascript 之执行环境-08
概念 执行环境(Execution context,简称EC)或执行上下文对象(后面统一用执行上下文表示),它定义了变量或者函数有权访问的其他数据,决定了他们各自的行为.是不是有点不好理解,那我先简单 ...
- 树的三种遍历方式(C语言实现)
//************************************************************************* // [前序]遍历算法 //二叉树不空,先访问根 ...
- poj 3340 Barbara Bennett's Wild Numbers(数位DP)
Barbara Bennett's Wild Numbers Time Limit: 2000MS Memory Limit: 65536K Total Submissions: 3153 A ...
- HDU 1892 See you~(二维树状数组)
See you~ Time Limit: 5000/3000 MS (Java/Others) Memory Limit: 65535/32768 K (Java/Others)Total Su ...
- 《Github入门与实践》读书笔记 蟲咋先生的追求之旅(上)
<Github入门与实践>作者: [日] 大塚弘记 译者:支鹏浩/刘斌 简介 本书从Git的基本知识和操作方法入手,详细介绍了GitHub的各种功能,GitHub与其他工具或服务的协作 ...
- 轻松驾驭Tomcat
Tomcat 服务器是一个免费的开放源代码的Web 应用服务器,属于轻量级应用服务器,在中小型系统和并发访问用户不是很多的场合下被普遍使用,是开发和调试JSP 程序的首选.对于一个初学者来说,可以这样 ...