Swagger
随着前后端分离架构和微服务架构地流行,我们使用Spring Boot来构建RESTful API项目的场景越来越多,在多人协作的团队中,前后端的沟通成本往往比较大。在这样的背景下,Swagger出现了(当然还有其他的就不一一例举了)。
使用 Swagger 集成文档具有以下几个优势:
- 功能丰富 :支持多种注解,自动生成接口文档界面,支持在界面测试API接口功能
- 及时更新 :开发过程中花一点写注释的时间,就可以及时的更新API文档,省心省力
- 整合简单 :通过添加pom依赖和简单配置,内嵌于应用中就可同时发布API接口文档界面,不需要部署独立服务
开始整合Swagger2
在上一篇的项目基础上,我们来使用一下Swagger。
- 首先,我们需要在pom.xml中添加依赖,如下:
io.springfox springfox-swagger2 2.9.2io.springfox springfox-swagger-ui 2.9.2
- 接下来我们来编写一个SwaggerConfig配置类
新建一个包:com.zhlab.demo.config,创建SwaggerConfig类
SwaggerConfig.java
package com.zhlab.demo.config;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.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;/** * @ClassName SwaggerConfig * @Description //SwaggerConfig配置类 * @Author singleZhang * @Email 405780096@qq.com * @Date 2020/10/17 0017 上午 11:11 **/@Configuration@EnableSwagger2public class SwaggerConfig { @Bean public Docket creatRestApi(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(this.apiInfo()) .select() //扫描指定路径 .apis(RequestHandlerSelectors.basePackage("com.zhlab.demo.controller")) // 扫描所有有注解的api,用这种方式更灵活 //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) // 扫描所有 // .apis(RequestHandlerSelectors.any()) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo(){ return new ApiInfoBuilder() .title("zhLab Demo Api Doc") .description("api document of zhLab Demo") .version("1.0.1") .build(); }}
※说明:
- 在类上,添加 @EnableSwagger2 注解, 标记项目启用 Swagger API 接口文档。
- 通过 createRestApi() 方法,创建 Swagger Docket Bean
- 更多的配置可以在Docket.java、ApiInfo.java两个类的源码中查看
- 修改上一篇中的HelloController控制器
package com.zhlab.demo.controller;import io.swagger.annotations.ApiOperation;import io.swagger.annotations.ApiParam;import org.springframework.web.bind.annotation.*;/** * @ClassName HelloController * @Description //第一个Springboot接口 * @Author singleZhang * @Email 405780096@qq.com * @Date 2020/10/16 0016 上午 10:55 **/@RestController@RequestMapping("/system/user")public class HelloController { /* 方法注解 */ @ApiOperation(value = "方法名:打招呼", notes = "打招呼方法的测试") @GetMapping("/hello") public String sayHello(/* 参数注解 */ @ApiParam(value = "参数:名字" , required=true ) @RequestParam String name){ return "hi"+name+" ,I can say hello"; }}
启动项目,在浏览器输入http://localhost:8080/swagger-ui.html显示下图:
swagger-ui
执行一下,测试一下接口:
TEST
常用注解说明
swagger 通过注解接口生成文档,包括接口名,请求方法,参数,返回信息等。
@Api: 修饰整个类,用于controller类上
@ApiOperation: 描述一个接口,用户controller方法上
@ApiParam: 单个参数描述
@ApiModel: 用来对象接收参数,即返回对象
@ApiModelProperty: 对象接收参数时,描述对象的字段
@ApiResponse: Http响应其中的描述,在ApiResonse中
@ApiResponses: Http响应所有的描述,用在
@ApiIgnore: 忽略这个API
@ApiError: 发生错误地返回信息
@ApiImplicitParam: 一个请求参数
@ApiImplicitParam: 多个请求参数
总结
以上就是对Swagger的初步体验,前后端分离api文档是节省沟通成本的重要工具,用好它,你肯定会如虎添翼,以后还会推荐YAPI等工具。