springboot配置swagger2生成Api文档

在前后端分离开发中，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

---

2023-08-31 记录：
发现了一个问题，如果IDEA使用了JRebel热部署插件，启动项目后可能会导致swagger文档的响应示例为空，如果要联调的时候，慎用热部署