关键词:
在前后联调时,一个高质量的接口文档工具是必不可少的。否则就会出现前后台人员不停的来回沟通的现象,浪费大量的时间。在大多数企业的接口文档使用的都是swaager,可能唯一的缺陷就是ui样式不是特别给力。但是有大量的增强性工具可以使用,如yapi,其中支持swagger导出文件的展示。
如果选择其他接口文档工具,可能对比swagger有缺失。请谨慎选择。
博主在公司规定定义时,规定入参值与返回值均为实体类,不允许使用其他基本类型的封装类型。以下使用均在此前提。这里就面临这get请求的问题,如果有兴趣可以接续往下看。
1.整合springboot
1.pom文件新增
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>
2.新增config文件
@Configuration
public class SwaggerConfig
@Bean
public Docket createRestApi()
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//controller包
.apis(RequestHandlerSelectors.basePackage("com.airboot.bootdemo.controller"))
.paths(PathSelectors.any())
.build();
private ApiInfo apiInfo()
return new ApiInfoBuilder()
.title("文档标题")
.description("文档描述")
.termsOfServiceUrl("http://blog.csdn.net/saytime")
.version("1.0")
.build();
3.application中添加注解
这里需要添加增加@EnableSwagger2注解。
@SpringBootApplication
@EnableSwagger2
public class BootdemoApplication
public static void main(String[] args)
SpringApplication.run(BootdemoApplication.class, args);
以上步骤完成后,就可以使用了,可以访问http://localhost:[端口]/swagger-ui.html#/
附上文件结构
2.接口使用swagger2
1.修改实体类
如果需要返回的实体类带中文名称需要以下配置。
@ApiModel(value="DemoVO",description="对象")
public class DemoVO
private static final long serialVersionUID = -1L;
/**
* 城市编号
*/
@ApiModelProperty(value="id",name="id")
private Long id;
/**
* 省份编号
*/
@ApiModelProperty(value="省份编号",name="省份编号")
private Long provinceId;
/**
* 城市名称
*/
@ApiModelProperty(value="城市名称",name="城市名称")
private String cityName;
/**
* 描述
*/
@ApiModelProperty(value="描述",name="描述")
private String description;
2.修改接口
1.入参为String出参为List
此种方式在博主公司不允许出现。
/**
* 通过参数查询(多个入参)
*
* @return
*/
@RequestMapping(value = "/selectDemoByParas", method = RequestMethod.GET)
@ApiOperation(value = "查询城市信息", notes = "根据入参查询城市demo(入参为Long)")//notes 描述
@ApiImplicitParams(
@ApiImplicitParam(name = "id", value = "主键", required = true, dataType = "Long", paramType = "path"), //required 是否必填,dataType入参类型
@ApiImplicitParam(name = "provinceId", value = "省份id", required = false, dataType = "Long", paramType = "path")
)
@ApiResponses(value =
@ApiResponse(code = 200, message = "成功"),
@ApiResponse(code = 400, message = "参数格式错误"),
@ApiResponse(code = 401, message = "登录错误"),
@ApiResponse(code = 404, message = "未找到地址"),
@ApiResponse(code = 500, message = "服务器错误")
)
public List<DemoVO> selectDemoByParas(@RequestParam("id") Long id, @RequestParam("provinceId") Long provinceId)
DemoVO inputVO = new DemoVO();
inputVO.setId(id);
return demoService.selectDemoVO(inputVO);
以上是文档效果,同时respones class下的model和model schema可以更换返回对象样式。
可以通过try it out测试接口 同时可以切换显示注释的中文名称和json格式。
2.入参为实体,出参为list
1.post方式
@RequestMapping(value = "/selectDemoByVo", method = RequestMethod.POST)
@ApiOperation(value = "查询城市信息", notes = "根据入参查询城市demo")
//入参是pojo有三种方法
//1.@ApiParam
//2.@ApiImplicitParam(name = "demoVO", value = "入参为VO", required = false, dataType = "DemoVO")
//3.@ApiImplicitParams(
//@ApiImplicitParam(name = "id", value = "主键", required = true, dataType = "Long", paramType = "path"),
//@ApiImplicitParam(name = "provinceId", value = "省份id", required = false, dataType = "Long", paramType = "path")
//)
//!!!!但是建议使用@ApiParam 这样可以显示出入参格式和中文名称 如例
public List<DemoVO> selectDemoByVo(@RequestBody @ApiParam(name = "用户对象", value = "传入json格式", required = true) DemoVO demoVO)
return demoService.selectDemoVO(demoVO);
2.get方式
@Log(operationName = "机构部门-查询工作组用户")
@GetMapping("/selectWorkSysUser")
@ApiOperation(value = "通过实体查询用户", notes = "通过实体查询用户")
public Result<List<SysUserVO>>
selectWorkSysUser(@ApiParam(name = "入参对象", value = "实体", required = false) SysUserVO sysSysUserVO) throws TemplateException
以上是效果,同时respones class和parameters都可以选择样式。
3.入参为List,出参为List
/**
* 通过List查询
*
* @param demoVO
* @return
*/
@RequestMapping(value = "/selectDemoByList", method = RequestMethod.POST)
@ApiOperation(value = "查询城市信息", notes = "根据入参查询城市demo")
@ApiImplicitParam(name = "demoVO", value = "入参为List", required = false, dataType = "List<DemoVO>")
public List<DemoVO> selectDemoByList(@RequestBody List<DemoVO> demoVO)
return demoService.selectDemoVO(demoVO.get(0));
以上是效果,同以上相同
三 常用注解含义
controller类使用
@Api:修饰整个类,描述Controller的作用
@ApiOperation:描述一个类的一个方法,或者说一个接口
@ApiImplicitParams:多个请求参数(一个@ApiImplicitParams包括多个
@ApiImplicitParam)
@ApiImplicitParam:一个请求参数
@ApiResponses:HTTP响应整体描述(一个@ApiResponses包括多个@ApiResponse)
@ApiResponse:HTTP响应其中1个描述
@ApiIgnore:使用该注解忽略这个API
@ApiError :发生错误返回的信息
@ApiParam:单个参数描述
实体类pojo使用
@ApiModel:用对象来接收参数(pojo类使用)
@ApiProperty:用对象接收参数时,描述对象的一个字段(pojo类的参数使用)
企业级springboot落地:连接内外网邮箱,实现邮件提醒功能(代码片段)
...f0c;或者事件办完后,经常有邮件通知提醒的需求。而springboot也提供了start,只需要按照要求调用方法即可。但是网络上大多事如何调用外网邮箱的博文,本文将分别实现如何调用内外网邮件。1.业务代码1.pom文件<dep... 查看详情
springboot之swagger2
SpringBoot利用Swagger2只需配置少量的注解信息便能方便地构建强大的API文档。1、添加maven依赖 2、创建Swagger2配置类 3、在API添加文档内容 4、访问http://localhost:8080/swagger-ui.html 查看详情
最火热的极速开发框架springboot
联席作者:谢璐谢庆芳伊安娜任浩军<br/>郑重鸣谢:Nacos-彦林,SpringCloudAlibaba-小马哥、洛夜,Nacos社区-张龙(pader)、春少(chuntaojun)相关文章推荐:掌门教育微服务体系Solar|阿里巴巴Nacos企业级落地上篇掌门教育微服务体... 查看详情
springboot集成swagger2在线文档
目录SpringBoot集成Swagger2在线文档前言集成SpringBoot登录接口文档示例代码效果注解说明总结SpringBoot集成Swagger2在线文档前言不得不说,前后端分离开发的工作方式给我们带来诸多好处,让前后端攻城狮们顺畅了不少后端给前端提... 查看详情
springboot之swagger2集成
一、Swagger2简单介绍 Swagger2,它可以轻松的整合到SpringBoot中,并与SpringMVC程序配合组织出强大RESTfulAPI文档。它既可以减少我们创建文档的工作量,同时说明内容又整合入实现代码中,让维护文档和修改代码整合为一体,可以... 查看详情
springboot整合swagger2搭建api在线文档
...阅和测试功能。利用Swagger2很容易构建RESTful风格的API,在SpringBoot中集成Swagger2,步骤如下。1.引入依赖<!--Swagger2--><dependency><groupId> 查看详情
springboot1.5.4集成swagger2构建restfulapi(十八)
上一篇博客地址:springboot1.5.4整合rabbitMQ(十七)1 SpringBoot集成Swagger2构建RESTfulAPI文档1.1 Swagger2简介Swagger2官网:http://swagger.io/由于SpringBoot能够快速开发、便捷部署等特性,相信有很大一部分SpringBoo 查看详情
springboot入门:集成swagger2
本片文章是基于前一篇写的,《SpringBoot入门(六):集成treetable和zTree实现树形图》,本篇主要介绍了springboot集成swagger2。关于swagger的介绍,自行谷歌。我这里有在网上购买的相关视频资料,有需要可以呼叫我。1.引入相关依赖... 查看详情
springboot集成swagger2生成api接口文档(代码片段)
SpringBoot2.3.0集成Swagger2引入Swagger2相应的依赖入门示例SpringBoot2集成Swagger2后启动报错结语背景:最近在工作中发现,已经多次发现后台开发人员提供的接口协议和实际的业务代码不统一。这些现象往往都是因为开发人员在... 查看详情
springboot项目配置swagger2示例(代码片段)
目录一、swagger2中常用的注解作用二、springboot项目配置swagger2步骤三、示例中使用的注解解析一、swagger2中常用的注解作用注解作用@Api修饰整个类,描述Controller的作用,表示标识这个类是swagger的资源@ApiOperation描述... 查看详情
springboot整合swagger2
SpringBoot整合Swagger2相信各位在公司写API文档数量应该不少,当然如果你还处在自己一个人开发前后台的年代,当我没说,如今为了前后台更好的对接,还是为了以后交接方便,都有要求写API文档。手写Api文档的几个痛点:文档需... 查看详情
springboot整合swagger2框架
一:什么是SwaggerSwagger是一款通过我们添加的注解来对方法进行说明,来自动生成项目的在线api接口文档的web服务。二:添加Swagger2依赖<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><ve 查看详情
springboot项目集成swagger2
一、前言现如今,前后端分离已经逐渐成为互联网项目一种标准的开发方式,前端与后端交给不同的人员开发,但是项目开发中的沟通成本也随之升高,这部分沟通成本主要在于前端开发人员与后端开发人员对WebAPI接口的沟通,... 查看详情
springboot+security+swagger2配置(代码片段)
SpringBoot+Security+Swagger2配置前言:本来想用Swagger3呢,但是找了好久都没有找到Swagger3的文档,百度也搜不到。这里说的是添加security的登录、登出配置。所以就借用了网上的部分代码做的首先在pom.xml中添加swagger2... 查看详情
springboot中使用swagger2构建restfulapis(含源码)
Swagger2简介本次教程是SpringBoot中使用Swagger2构建RESTfulAPISSwagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。(如图)Swagger除了查看接口功能外,还提供了调试测试功能。(如... 查看详情
springboot继承swagger2
1、添加pom依赖:<!--添加swagger相关依赖--><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.7.0</version></depende 查看详情
springboot+swagger2说明
swagger用于定义API文档。优势:前后端分离开发API文档非常明确测试的时候不需要再使用URL输入浏览器的方式来访问Controller传统的输入URL的测试方式对于post请求的传参比较麻烦(当然,可以使用postman这样的浏览器插... 查看详情
springboot之集成swagger2
maven配置<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.5.0</version></dependency><dependency>< 查看详情