在前后端分离开发中，Swagger2可以帮助开发人员设计、构建、记录和使用RESTful Web服务，仅用注解就可以将代码和文档融为一体，大大减少了与其他团队的沟通成本。下面我们用SpringBoot来配置swagger2
一、引入swagger 2依赖
<!-- 整合swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>3.0.0</version>
</dependency>
二、创建Swagger 2配置类
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).select()
.apis(RequestHandlerSelectors.basePackage("com.cn.question.controller")) // 配置要扫描的controller位置
.paths(PathSelectors.any()) // paths方法配置路径
.build()
.apiInfo(new ApiInfoBuilder() // apiInfo方法构建文档的基本信息
.title("题库API接口文档") // 标题
.description("题库接口相关文档") // 描述
.version("V1.0.0") // 版本
.contact(new Contact("Unique", // 作者信息
"https://blog.csdn.net/weixin_47390965?type=blog",
"1196302555@qq.com"))
.build());
}
}
三、控制层代码
@Api(tags = "数学题接口")
@RestController
@RequestMapping("/math/arithmetic")
public class ArithmeticController {
@Autowired
private ArithmeticService arithmeticService;
/**
* 随机算术题出题接口
*
* @param operator 运算方式
* @param range 运算范围
* @return Result<TitleDTO>
*/
@ApiOperation("随机算术题出题接口")
@ApiImplicitParams({
@ApiImplicitParam(name = "operator", value = "运算方式", required = true, paramType = "path"),
@ApiImplicitParam(name = "range", value = "运算范围", required = true, paramType = "query")
})
@GetMapping("/{operator}")
public Result<TitleDTO> getArithmeticQuestions(@PathVariable int operator, @RequestParam int range) {
if (operator == 0) {
Random random = new Random();
operator = random.nextInt(4) + 1;
}
return arithmeticService.getArithmeticQuestions(operator, range);
}
/**
* 随机算术题答题接口
*
* @param titleDTO 答题参数
* @return Result<String>
*/
@ApiOperation("随机算术题答题接口")
@ApiImplicitParam(name = "titleDTO", value = "答题参数", required = true, paramType = "form")
@PostMapping("/title")
public Result<String> answerQuestion(@RequestBody TitleDTO titleDTO) {
return arithmeticService.answerQuestion(titleDTO);
}
}
主要注解：
@Api注解用在类上，用于描述Controller信息@ApiOperation注解用在方法上，用于描述方法的基本信息@ApiImplicitParam注解用在方法上，用于描述方法需要的参数：- paramType是指方法参数的类型，可选值有path（参数获取方式@PathVariable）、query（参数获取方式@RequestParam）、header（参数获取方式@RequestHeader）、body以及form（参数获取方式@RequestBody）；
- name表示参数名称，和参数变量对应；
- value是参数的描述信息；
- required表示该字段是否必填；
- defaultValue表示该字段的默认值；
- 注意，这里的required和defaultValue等字段只是文档上的约束描述，并不能真正约束接口，约束接口还需要在@RequestParam中添加相关属性
- 如果方法有多个参数，可以将多个参数的
@ApiImplicitParam注解放到@ApiImplicitParams中 - 还有
@ApiResponse注解，这里我没有用到，它是对响应结果的描述，code表示响应码，message表示相应的描述信息，若有多个@ApiResponse，则放在一个@ApiResponses中
四、实体类代码
实体类中可以使用@ApiModel注解和@ApiModelProperty注解配置对象的描述信息
@Data
@ApiModel("答题参数信息")
public class TitleDTO {
@ApiModelProperty(value = "第一个数字")
private Integer frontNumber;
@ApiModelProperty(value = "第二个数字")
private Integer afterNumber;
@ApiModelProperty(value = "运算符")
private String operator;
@ApiModelProperty(value = "答案")
private Double answer;
...
}
五、启动项目查看文档
项目启动成功后，在浏览器输入http://localhost:8087/swagger-ui.html即可查看文档，可以看到我们在配置文件中配置的描述信息
展开数学题接口，可以看到所有描述的接口
展开接口描述，可以看到接口需要的信息参数，点击 Try It out 按钮可以测试
六、优化文档界面
swagger-ui的界面属实不大好看，可以引入knife4j依赖来美化一下，让文档看起来更加一目了然
<!-- swagger界面美化 -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.3</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
</dependency>
在swagger配置类上加入@EnableKnife4j注解即可，启动成功后访问http://localhost:8087/doc.html
可以看到比之前的界面看起来舒服很多了~
六、可能遇到的报错问题解决
在启动的时候，碰到了这个问题 Failed to start bean ‘documentationPluginsBootstrapper’; nested exception is java.lang.NullPointerException
这是因为SpringBoot的版本可能与swagger2不匹配，可以适当的降低一下SpringBoot的版本，我这边现在使用的是2.5.4
完。