背景:
最近进行项目优化,增添swagger功能方便接口测试!
一、SWAGGER简介
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。
作用:
- 接口的文档在线自动生成。
- 功能测试。
Swagger是一组开源项目,其中主要要项目如下:
Swagger-tools
:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。Swagger-core
: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF…)、Servlets和Play框架进行集成。Swagger-js
: 用于JavaScript的Swagger实现。Swagger-node-express
: Swagger模块,用于node.js的Express web应用框架。Swagger-ui
:一个无依赖的HTML、JS和CSS集合,可以为Swagger兼容API动态生成优雅文档。Swagger-codegen
:一个模板驱动引擎,通过分析用户Swagger资源声明以各种语言生成客户端代码。
二、SPRINGBOOT整合流程
1.POM.XML中添加MAVEN依赖
此处需要注意的是版本问题,高版本的swagger必须对应高版本的springboot,我们项目集成的是 springboot1.5.9
+ swagger2.2.2
<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.增加SWAGGERCONFIG配置类
/** * Swagger配置类 * @Author: yuanj * @Date: 2018/9/17 13:43 */ @Configuration @EnableSwagger2 @ConditionalOnProperty(prefix = "msg-config", name = "swagger-open", havingValue = "true") public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //这里采用包含注解的方式来确定要显示的接口 //.apis(RequestHandlerSelectors.basePackage("com.moerlong.service_authorize.controller")) //这里采用包扫描的方式来确定要显示的接口 .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("MoerService Gateway Doc") //标题 .description("摩尔服务授权网关 Api文档") //描述 .termsOfServiceUrl("http://www.moerlong.com") //条款地址(不可见) .contact("moerlong") //作者信息 .version("1.0") //版本号 .build(); } }
注意此处使用了@ConditionalOnProperty
标签,可以配合application.yml进行swagger的开关配置:
@ConditionalOnProperty(prefix = "msg-config", name = "swagger-open", havingValue = "true")
application.yml 中添加:
msg-config: swagger-open: true
其中name用来从application.yml中读取某个属性值,如果该值为空,则返回false;如果值不为空,则将该值与havingValue指定的值进行比较,如果一样则返回true;否则返回false。如果返回值为false,则该configuration不生效;为true则生效。
3.在CONTROLLER层添加相关注解
Swagger使用的注解及其说明:
@Api
:用在类上,说明该类的作用。
@ApiOperation
:注解来给API增加方法说明。
@ApiImplicitParams
: 用在方法上包含一组参数说明。
@ApiImplicitParam
:用来注解来给方法入参增加说明。
@ApiResponses
:用于表示一组响应
@ApiResponse
:用在@ApiResponses中,一般用于表达一个错误的响应信息
@ApiModel
:描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)
@ApiImplicitParam
的参数说明:
注:paramType 必须与方法参数获取使用的注解一致,不然无法接受到参数值
实际案例:
@RestController @RequestMapping("/teacher") @Api(value = "UserController", description = "老师相关接口") public class TeacherController { @Autowired private TeacherService teacherSvc; @OpenApi @RequestMapping(value = "findPage", method = RequestMethod.POST) @ApiOperation(value = "findPage", notes = "首页查询老师列表") public ResponseFindPage<TeacherResponse> findPage(@RequestBody TeacherSearchRequest body) { return teacherSvc.findPage(body); } @OpenApi @RequestMapping(value = "auth", method = RequestMethod.GET) @ApiOperation(value = "auth", notes = "鉴权") @ApiImplicitParams({ @ApiImplicitParam(paramType = "query", name = "code", value = "code", required = true, dataType = "String"), @ApiImplicitParam(paramType = "query", name = "encryptedData", value = "encryptedData", required = true, dataType = "String"), @ApiImplicitParam(paramType = "query", name = "iv", value = "iv", required = true, dataType = "String") }) public ResponseMessage<UserResponse> auth(@RequestParam String code, @RequestParam String encryptedData, @RequestParam String iv) { return userService.auth(code, encryptedData, iv); } }
4.访问SWAGGER地址
默认地址:http://localhost:8885/swagger-ui.html
参考原文:https://www.freesion.com/article/9180461/
代码改变世界!