💘10分钟,6个点,SpringBoot集成丝袜哥(Swagger)整的明明白白💘
1. 什么是Swagger
相信无论是前端还是后端开发,都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力,经常来不及更新。其实无论是前端调用后端,还是后端调用后端,都期望有一个好的接口文档。但是这个接口文档对于程序员来说,就跟注释一样,经常会抱怨别人写的代码没有写注释,然而自己写起代码起来,最讨厌的,也是写注释。所以仅仅只通过强制来规范大家是不够的,随着时间推移,版本迭代,接口文档往往很容易就跟不上代码了。
发现了痛点就要去找解决方案。解决方案用的人多了,就成了标准的规范,这就是Swagger的由来。通过这套规范,你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具,就可以做到生成各种格式的接口文档,生成多种语言的客户端和服务端的代码,以及在线接口调试页面等等。这样,如果按照新的开发模式,在开发新版本或者迭代版本的时候,只需要更新Swagger描述文件,就可以自动生成接口文档和客户端服务端代码,做到调用端代码、服务端代码以及接口文档的一致性。
但即便如此,对于许多开发来说,编写这个yml或json格式的描述文件,本身也是有一定负担的工作,特别是在后面持续迭代开发的时候,往往会忽略更新这个描述文件,直接更改代码。久而久之,这个描述文件也和实际项目渐行渐远,基于该描述文件生成的接口文档也失去了参考意义。所以作为Java届服务端的大一统框架Spring,迅速将Swagger规范纳入自身的标准,建立了Spring-swagger项目,后面改成了现在的Springfox。通过在项目中引入Springfox,可以扫描相关的代码,生成该描述文件,进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式,在后面需求持续迭代的项目中,显得尤为重要和高效。
2. Swagger注解详解
2.1 @Api
@Api 用在类上,说明该类的作用。可以标记一个 Controller 类作为 Swagger 文档资源
tags:接口说明,可以在页面中显示。可以配置多个,当配置多个的时候,在页面中会显示多个接口的信息。description:对tags 进行描述说明
@RequestMapping("/api")
@Api(tags = "测试swagger接口",description = "User模块")//描述
2.2 @ApiModel
@ApiModel 用在类上,表示对类进行说明,用于实体类中的参数接收说明
@Data
@ApiModel(value = "com.pojo",description = "用户pojo")
public class User {
@ApiModelProperty(value = "账号")
private String username;
@ApiModelProperty(value = "密码")
private String password;
}
2.3 @ApiModelProperty
@ApiModelProperty() 用于字段,表示对 model 属性的说明
package com.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
@Data
@ApiModel(value = "com.pojo",description = "用户pojo")
public class User {
@ApiModelProperty(value = "账号")
private String username;
@ApiModelProperty(value = "密码")
private String password;
}
2.4 @ApiParam
@ApiParam 用于 Controller 中方法的参数说明
- value:参数说明
- required:是否必填
@RestController
@RequestMapping("/api")
@Api(tags = "测试swagger接口",description = "User模块")//描述
public class SwaggerController {
@ApiOperation(value = "我的第一个swagger接口")
@PostMapping("/swagger")
public User testUser(@ApiParam(value = "用户实体",required = true) @RequestBody User user, HttpServletRequest request){
System.out.println(request.getHeader("token"));
return user;
}
}
2.5 @ApiOperation
@ApiOperation 用在 Controller 里的方法上,说明方法的作用,每一个接口的定义
value:接口名称
@RestController
@RequestMapping("/api")
@Api(tags = "测试swagger接口",description = "User模块")//描述
public class SwaggerController {
@ApiOperation(value = "我的第一个swagger接口")
@PostMapping("/swagger")
public User testUser(@ApiParam(value = "用户实体",required = true) @RequestBody User user, HttpServletRequest request){
System.out.println(request.getHeader("token"));
return user;
}
}
2.6 @ApiResponse 和 @ApiResponses
@ApiResponse 用于方法上,说明接口响应的一些信息;@ApiResponses 组装了多个 @ApiResponse
@GetMapping("/getUser")
@ApiOperation(value = "获取用户信息接口")
@ApiResponses({ @ApiResponse(code = 0, message = "相应成功", response = SysUser.class) })
public SysUser getUserInfo(@ApiParam(value = "用户id",required = true) @RequestParam String id){
return userService.getUserInfo(id);
}
2.7 @ApiImplicitParam 和 @ApiImplicitParams
用于方法上,为单独的请求参数进行说明
@GetMapping("/getUser")
@ApiOperation(value = "获取用户信息接口")
@ApiResponses({ @ApiResponse(code = 0, message = "相应成功", response = SysUser.class) })
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户id", dataType = "string", paramType = "query",
required = true, defaultValue = "0f09e661-7e80-4e1b-b66a-2e266bb593bf")
})
public SysUser getUserInfo(@ApiParam(value = "用户id",required = true) @RequestParam String id){
return userService.getUserInfo(id);
}
3. 引入Swagger的jar
<!--swagger2 依赖-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
</dependency>
4. 创建Swagger的配置类
package com.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
import java.util.List;
@Configuration//表示这是一个配置类
@EnableSwagger2//开启Swagger2
public class SwaggerConfig {
@Bean
public Docket reeateDocket(){
List<Parameter> parameterList=new ArrayList<>();
ParameterBuilder parameterBuilder=new ParameterBuilder();
parameterBuilder.name("token")
.description("swagger调试用,模拟传入用户凭证")
.modelRef(new ModelRef("String"))
.parameterType("header").required(false);
parameterList.add(parameterBuilder.build());
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())//创建该Api的基本信息(这些基本信息会展现在文档页面中)
.select()//函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger ui来展现
.apis(RequestHandlerSelectors.basePackage("com.controller"))//指定需要扫描的包路路径
.paths(PathSelectors.any())
.build()
.globalOperationParameters(parameterList)
;
}
//配置swagger的信息
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("spring boot2.x实战")
.description("整合swagger")
.termsOfServiceUrl("")
.version("2.0")
.build();
}
}
5. 实体类创建
package com.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
@Data
@ApiModel(value = "com.pojo",description = "用户pojo")
public class User {
@ApiModelProperty(value = "账号")
private String username;
@ApiModelProperty(value = "密码")
private String password;
}
6. 测试类创建
package com.controller;
import com.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.http.HttpRequest;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import javax.servlet.http.HttpServletRequest;
@RestController
@RequestMapping("/api")
@Api(tags = "测试swagger接口",description = "User模块")//描述
public class SwaggerController {
@ApiOperation(value = "我的第一个swagger接口")
@PostMapping("/swagger")
public User testUser(@ApiParam(value = "用户实体",required = true) @RequestBody User user, HttpServletRequest request){
System.out.println(request.getHeader("token"));
return user;
}
}
7. 测试
- 点赞
- 收藏
- 关注作者
评论(0)