springmvc+swagger构建Restful风格文档
本次和大家分享的是java方面的springmvc来构建的webapi接口+swagger文档;上篇文章分享.net的webapi用swagger来构建文档,因为有朋友问了为啥.net有docpage文档你还用swagger,这里主要目的是让接口文档统一,当操作多种开发语言做接口时,如果有统一风格的api文档是不是很不错;还有就springcloude而言,微服务如果有很多的话,使用swagger自动根据服务serverid来加载api文档是很方便的。swagger设置比较简单,为了今后查找资料和使用方便故此记录下
- 准备工作
- 快速构建api文档
- 常用的细节
- 过滤默认错误api
- 添加授权token列
- 添加上传文件列
准备工作
首选需要一个springmvc项目,这里我用的是springboot+maven来快速构建, 要使用swagger只需要在maven中添加依赖包就行:
1 <dependency> 2 <groupId>io.springfox</groupId> 3 <artifactId>springfox-swagger2</artifactId> 4 <version>2.6.1</version> 5 </dependency> 6 <dependency> 7 <groupId>io.springfox</groupId> 8 <artifactId>springfox-swagger-ui</artifactId> 9 <version>2.6.1</version> 10 </dependency>
然后创建一个UserController,然后再定义个Login的Action,定义请求和响应实体,由于api接口需要对请求和响应属性列做 文字描述,并且上面我们在项目中加了swagger包,因此以直接在实体和Action使用特性来增加具体文字描述:
1 @RestController 2 @Api(tags = "会员接口") 3 public class UserController { 4 5 @PostMapping("/login") 6 @ApiOperation(value = "登录") 7 public LoginRp login(@RequestBody LoginRq rq) { 8 LoginRp rp = new LoginRp(); 9 10 if (rq.getUserName().isEmpty() || rq.getUserPwd().isEmpty()) { 11 rp.setCode(EmApiCode.登录账号或密码不能为空.getVal()); 12 return rp; 13 } 14 15 if (rq.getUserName().equals("shenniu001") && rq.getUserPwd().equals("123")) { 16 rp.setCode(EmApiCode.成功.getVal()); 17 18 rp.setToken(UUID.randomUUID().toString()); 19 } else { 20 rp.setCode(EmApiCode.失败.getVal()); 21 } 22 return rp; 23 } 24 25 }
请求和响应实体类:
1 @ApiModel 2 public class LoginRq implements Serializable{ 3 4 private static final long serialVersionUID = -158328750073317876L; 5 6 @ApiModelProperty(value = "登录账号") 7 private String userName; 8 9 @ApiModelProperty(value = "登录密码") 10 private String userPwd; 11 12 } 13 14 @ApiModel 15 public class LoginRp extends BaseRp implements Serializable { 16 private static final long serialVersionUID = -1486838360296425228L; 17 18 @ApiModelProperty(value = "授权token") 19 private String token; 20 21 public String getToken() { 22 return token; 23 } 24 25 public void setToken(String token) { 26 this.token = token; 27 } 28 }
注解简单说明:
@Api:同一类接口的总描述,一般用于Controller标记
@ApiOperation(value = "登录"):在Action上标记,描述这个Action接口具体干什么
@ApiModel:请求响应实体类class上的标记
@ApiModelProperty(value = "登录账号"):请求响应属性上的标记,用来描述该属性具体说明
快速构建api文档
准备做完后要生成文档,还需要自定义两个封装类,如下Swagger2类:
1 @Configuration 2 @EnableSwagger2 3 public class Swagger2 { 4 5 @Bean 6 public Docket createRestApi() { 7 8 return new Docket(DocumentationType.SWAGGER_2) 9 .select() 10 //过滤默认错误api 11 .paths(Predicates.not(PathSelectors.regex("/error.*"))) 12 .build() 13 .apiInfo(apiInfo()); 14 } 15 16 //常用的细节 17 //过滤指定的action 18 //添加授权token列 19 //添加上传文件列 20 private ApiInfo apiInfo() { 21 return new ApiInfoBuilder() 22 .title("开车接口文档") 23 .description("该文档只允许我使用") 24 //版本 25 .version("0.0.0.1") 26 .contact("作者:841202396@qq.com") 27 .build(); 28 } 29 }
这个类主要初始化一些全局文档的说明和版本并且构架api文档;上面是生成文档,但是具体文档数据源用从swagger的SwaggerResourcesProvider中来,因此自定义的DocumentationConfig类实现SwaggerResourcesProvider接口,如下:
1 @Component 2 @Primary 3 public class DocumentationConfig implements SwaggerResourcesProvider { 4 @Override 5 public List<SwaggerResource> get() { 6 List resources = new ArrayList<>(); 7 resources.add(swaggerResource("开车接口api", "/v2/api-docs", "0.0.0.1")); 8 resources.add(swaggerResource("坐车接口api", "/v2/api-docs", "0.0.0.1")); 9 return resources; 10 } 11 12 private SwaggerResource swaggerResource(String name, String location, String version) { 13 SwaggerResource swaggerResource = new SwaggerResource(); 14 swaggerResource.setName(name); 15 swaggerResource.setLocation(location); 16 swaggerResource.setSwaggerVersion(version); 17 return swaggerResource; 18 } 19 }
主要加载文档的数据源,数据源主要通过 resources.add(swaggerResource("坐车接口api", "/v2/api-docs", "0.0.0.1")) 添加,倘若你想添加其他api接口源就可以在这里进行配置,直接把/v2/api-docs改成你的url就行,这个地方也是springcloud微服务api添加的入口;当编码完成后我们来看看效果:
能成功加载出我们的login接口,而且有一些说明性的文字;再来看看我们请求和响应的参数是否有说明:
请求和响应都有了相应的说明,是不是挺简单;
常用的细节
1.过滤默认错误api
由于springmvc封装有错误的controller,因此swagger也会把这个展示出来,因为是扫描的所有controller来展示swagger文档的,故此我们需要屏蔽这些对于对接方没用的接口;这里通过设置paths的不匹配就行了,以下代码:
1 //过滤默认错误api 2 paths(Predicates.not(PathSelectors.regex("/error.*")))
2.添加授权token列
对于接口验证来说通常需要个token并且放在header里面,这里我们直接在swagger上增加一个显示的token,只需要在build之前增加一个header参数:
1 @Bean 2 public Docket createRestApi() { 3 4 List<Parameter> pars = new ArrayList<>(); 5 //添加授权token 6 ParameterBuilder tokenPar = new ParameterBuilder(); 7 tokenPar.name("token").description("授权token 注:登录不需要填,只有post方式的接口必填"). 8 modelRef(new ModelRef("string")). 9 parameterType("header").required(false).build(); 10 pars.add(tokenPar.build()); 11 12 return new Docket(DocumentationType.SWAGGER_2) 13 .select() 14 .paths(Predicates.not(PathSelectors.regex("/error.*"))) 15 .build() 16 .globalOperationParameters(pars) 17 .apiInfo(apiInfo()); 18 }
这个时候每个action接口文档块中都会增加一个token列,type是header类型:
3.添加上传文件列
通常api接口都包含一个公共上传接口,为了让swagger文档更方便,我们需要让她支持下上传;首先这样定义一个上传接口:
1 @PostMapping(value = "/upload",headers = "content-type=multipart/form-data") 2 @ApiOperation(value = "上传") 3 public BaseRp upload(@ApiParam(value = "上传的文件",required = true) @RequestBody MultipartFile file) { 4 BaseRp rp = new BaseRp(); 5 6 rp.setMessage("上传文件名:"+file.getOriginalFilename()); 7 8 return rp; 9 }
其他就不用再设置了,仅仅如此运行后效果:
咋们点击“选择文件”测试下上传,点击try能够得到如下成功运行的效果图:
低调大师中文资讯倾力打造互联网数据资讯、行业资源、电子商务、移动互联网、网络营销平台。
持续更新报道IT业界、互联网、市场资讯、驱动更新,是最及时权威的产业资讯及硬件资讯报道平台。
转载内容版权归作者及来源网站所有,本站原创内容转载请注明来源。
- 上一篇
用ASP.NET Core 2.0 建立规范的 REST API -- 预备知识
什么是REST REST 是 Representational State Transfer 的缩写. 它是一种架构的风格, 这种风格基于一套预定义的规则, 这些规则描述了网络资源是如何定义和寻址的. 一个实现了REST这些规则的服务就叫做RESTful的服务. 最早是由Roy Fielding提出的. RPC 风格 /getUsers /getUser?id=1 /createUser /deleteUser?id=4 /updateUser?name=dave 上面这些节点是针对User的CRUD操作. 这种样式风格的web服务更倾向于叫做RPC风格的服务. 在RPC的世界里, 节点仅仅就是可以在远程被触发的函数, 而在REST的世界里, 节点就是实体, 也叫做资源. REST的原则/约束 REST有6大原则/约束, 每一个原则都是对API有正面或负面影响的设计决定. RESTful API 最关心的有这几方面: 性能, 可扩展性, 简洁性, 互操作性, 通讯可见性, 组件便携性和可靠性. 这些方面被封装在REST的6个原则里, 它们是: 1. 客服端-服务端约束: 客户端和服务...
- 下一篇
【干货合集】项目管理、需求快速迭代如何实现?17篇文章搞懂敏捷开发!
为了让大家get到研发效能有关的敏捷开发和架构的相关知识,现将云栖社区2017年度与之相关的前沿技术理念及实践技术成果资料整理出来,供大家学习。 5月29日第二届研发效能嘉年华将邀请天猫、饿了么、飞猪的大咖,一起解读高效研发应该怎么做,戳链接免费预约在线直播!https://yq.aliyun.com/promotion/566 【敏捷开发】 敏捷个人和敏捷开发敏捷开发实践总结(一):敏捷开发的核心思想。谈谈软件项目管理——敏捷开发从瀑布模型、极限编程到敏捷开发敏捷开发思想及Scrum实践敏捷开发-快速迭代敏捷开发,你真的做对了吗?阿里文娱广告团队敏捷实践总结老曹眼中的敏捷开发【中生代北京闭门会实录】当深度学习遇上敏捷开发,会发生怎样的“化学反应”?还以为敏捷开发是个概念?有人已经将它变为现实了!敏捷开发敏捷开发的根本矛盾是什么?从业十余年的工程师在思考不以敏捷开发为基础的DevOps都是耍流流流流流流流氓敏捷开发 PK 瀑布模型敏捷开发解决方案敏捷开发之Scrum扫盲篇为什么敏捷开发在亚洲实行不了 上述是小编整理的最新关于“敏捷开发”的相关云栖社区博客,分享出来,便于大家对该架构有一...
相关文章
文章评论
共有0条评论来说两句吧...