在写这篇记录时swagger的最新版本到了3.0.0了在进行集成时没注意还按照2.0的集成走了一些弯路这里特记录下。
环境
一个已经搭建好的干净的springboot框架这个框架中我集成了mybatis.
什么是swagger
Swagger是一款RESTful接口的文档在线自动生成、功能测试功能框架。
一个规范和完整的框架用于生成、描述、调用和可视化RESTful风格的Web服务加上swagger-ui可以有很好的呈现。
当我们在后台的接口修改了后swagger可以实现自动的更新而不需要人为的维护这个接口进行测试。
说的再简单点传统的我们开发好接口后都会通过单元测试或者如PostMan之类的测试工具进行接口的测试在接口少的时候这个还行可是现在大家都倡导前后端分离式的开发
导致后端全是接口随着业务的复杂一个项目路的 接口不要太多每个接口我们都要去写文档而且在过程中随着业务的编写接口还会不停的更新这样我们的测试工具就显得力不从心了而且大家也知道很多公司的文档都是后补的各种各样的原因导致可能文档中的接口与实际的接口差别还挺大。。。。。
那么这个时候我们通过swagger的引入在写接口的同时通过注解的方式在接口上写明接口的作用参数介绍等那么会在线生成一个接口 文档而且还可以直接进行测试还是随着实际的接口变动实时更新的这个是不是挺美的。这就是swagger
但是swagger是侵入式的说白了你要用它就得在每个对应的接口的地方都要写点注解虽然少但还是有这就侵入了我们现有的代码这点目前看来不是很友好。
springBoot集成swagger
第一步引入maven依赖在你项目的pom文件中引入下面依赖
io.springfoxspringfox-boot-starter3.0.0
第二步添加配置我再启动类的同级目录下添加swagger的配置类
package com.nj.appserver;import io.swagger.annotations.ApiOperation;import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.service.ApiInfo;import springfox.documentation.service.Contact;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;/*** Swagger3配置类*/Configurationpublic class Swagger3Config {Beanpublic Docket createRestApi() {return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("Swagger3接口文档").description("更多请咨询服务开发者XXX").contact(new Contact("作者", "作者地址", "作者邮箱")).version("1.0").termsOfServiceUrl("aaa").build();}}
第三步在Application启动应用类上面加入EnableOpenApi注解
package com.nj.appserver;import org.springframework.boot.SpringApplication;import org.springframework.boot.autoconfigure.SpringBootApplication;import springfox.documentation.oas.annotations.EnableOpenApi;EnableOpenApiSpringBootApplicationpublic class AppServerApplication {public static void main(String[] args) {SpringApplication.run(AppServerApplication.class, args);}}
第四步在业务接口中添加swagger注解
package com.nj.appserver.controller;import com.github.pagehelper.PageHelper;import com.github.pagehelper.PageInfo;import com.nj.appserver.pojo.SysUser;import com.nj.appserver.service.SysUserService;import io.swagger.annotations.Api;import io.swagger.annotations.ApiOperation;import org.springframework.beans.factory.annotation.Autowired;import org.springframework.web.bind.annotation.GetMapping;import org.springframework.web.bind.annotation.RequestMapping;import org.springframework.web.bind.annotation.RequestParam;import org.springframework.web.bind.annotation.RestController;import java.util.List;Api(value "用户管理接口",tags "用户信息接口类")RestControllerRequestMapping("sysUser")public class SysUserController {Autowiredprivate SysUserService sysUserService;/*** 查询* return*/ApiOperation("查询用户列表")GetMapping("/findUserList")public List selectUserList(){List userList sysUserService.selectUserList();return userList;}/*** 分页查询* param pageNum 当前页数* param pageSize 每页的记录条数* return*/ApiOperation("分页查询用户列表")GetMapping("/findUserListByPage")public PageInfo getUserBySearch(RequestParam("pageNum") int pageNum,RequestParam("pageSize") int pageSize) {// TODO Auto-generated method stubPageHelper.startPage(pageNum,pageSize);List list sysUserService.selectUserList();PageInfo pageInfo new PageInfo(list);pageInfo.toString();return pageInfo;}}
第五步启动项目访问swaggerui界面注意swagger3更新后可访问ui界面路径与之前不同
http://localhost:【端口号】/[content-path]/swagger-ui/index.html
附常用的swagger注解
Api用在请求的类上表示对类的说明tags"说明该类的作用可以在UI界面上看到的注解"value"该参数没什么意义在UI界面上也看到所以不需要配置"ApiOperation用在请求的方法上说明方法的用途、作用value"说明方法的用途、作用"notes"方法的备注说明"ApiImplicitParams用在请求的方法上表示一组参数说明ApiImplicitParam用在ApiImplicitParams注解中指定一个请求参数的各个方面name参数名value参数的汉字说明、解释required参数是否必须传paramType参数放在哪个地方· header --> 请求参数的获取RequestHeader· query --> 请求参数的获取RequestParam· path用于restful接口--> 请求参数的获取PathVariable· body不常用· form不常用 dataType参数类型默认String其它值dataType"Integer" defaultValue参数的默认值ApiResponses用在请求的方法上表示一组响应ApiResponse用在ApiResponses中一般用于表达一个错误的响应信息code数字例如400message信息例如"请求参数没填好"response抛出异常的类ApiModel用于响应类上表示一个返回响应数据的信息这种一般用在post创建的时候使用RequestBody这样的场景请求参数无法使用ApiImplicitParam注解进行描述的时候ApiModelProperty用在属性上描述响应类的属性