java集成开发SpringBoot生成接口文档示例实现

目录

• 为什么要用Swagger ？
• Swagger集成
• 第一步： 引入依赖包
• 第二步：修改配置文件
• 第三步，配置API接口
• Unable to infer base url
• For input string: “”
• Swagger美化
• 第一步： 引入依赖包
• 第二步：启用knife4j增强
• Swagger参数分组
• 分组使用说明
• 1.在bean对象的属性里配置如下注释
• 2.在接口参数的时候加入组规则校验
• 小结

大家好，我是飘渺。

SpringBoot老鸟系列的文章已经写了两篇，每篇的阅读反响都还不错，果然大家还是对SpringBoot比较感兴趣。那今天我们就带来老鸟系列的第三篇：集成Swagger接口文档以及Swagger的高级功能。 文章涉及到的代码已经上传到了github，希望最终能应用在你们实际项目上，当然如果有其他需要我添加到内容也可以直接留言告诉我，我会视情况给你们加上去的。

SpringBoot 如何统一后端返回格式？老鸟们都是这样玩的！

SpringBoot 如何进行参数校验? 老鸟们都是这样玩的！

好了，闲话少叙，让我们先来看看为什么要用Swagger？

为什么要用Swagger ？

作为一名程序员，我们最讨厌两件事：1. 别人不写注释。2. 自己写注释。

而作为一名接口开发者，我们同样讨厌两件事：

1. 别人不写接口文档，文档不及时更新。

2. 需要自己写接口文档，还需要及时更新。

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。

而随着Springboot、Springcloud等微服务的流行，每个项目都有成百上千个接口调用，这时候再要求人工编写接口文档并且保证文档的实时更新几乎是一件不可能完成的事，所以这时候我们迫切需要一个工具，一个能帮我们自动化生成接口文档以及自动更新文档的工具。它就是Swagger。

Swagger 提供了一个全新的维护 API 文档的方式，有4大优点：

自动生成文档：只需要少量的注解，Swagger 就可以根据代码自动生成 API 文档，很好的保证了文档的时效性。

跨语言性，支持 40 多种语言。

Swagger UI 呈现出来的是一份可交互式的 API 文档，我们可以直接在文档页面尝试 API 的调用，省去了准备复杂的调用参数的过程。

还可以将文档规范导入相关的工具（例如 SoapUI）, 这些工具将会为我们自动地创建自动化测试。

现在我们知道了Swagger的作用，接下来将其集成到我们项目中。

Swagger集成

集成Swagger很简单，只需要简单三步。

第一步： 引入依赖包

    io.springfox
    springfox-swagger2
    2.9.2




    io.springfox
    springfox-swagger-ui
    2.9.2

第二步：修改配置文件

application.properties 加入配置

# 用于控制是否开启Swagger，生产环境记得关闭Swagger，将值设置为 false
springfox.swagger2.enabled = true

增加一个swagger配置类

@Configuration
@EnableSwagger2
@ConditionalOnClass(Docket.class)
public class SwaggerConfig {
  
    private static final String VERSION = "1.0";

    @Value("${springfox.swagger2.enabled}")
    private Boolean swaggerEnabled;

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(swaggerEnabled)
                .groupName("SwaggerDemo")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 添加摘要信息
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口文档")
                .contact(new Contact("JAVA日知录","http://javadaily.cn","[email protected]"))
                .description("Swagger接口文档")
                .version(VERSION)
                .build();
    }

}

这里通过 .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))

表面给加上 @Api注解的类自动生成接口文档。

第三步，配置API接口

@RestController
@Api(tags = "参数校验")
@Slf4j
@Validated
public class ValidController {

    @PostMapping("/valid/test1")
    @ApiOperation("RequestBody校验")
    public String test1(@Validated @RequestBody ValidVO validVO){
        log.info("validEntity is {}", validVO);
        return "test1 valid success";
    }

    @ApiOperation("Form校验")
    @PostMapping(value = "/valid/test2")
    public String test2(@Validated ValidVO validVO){
        log.info("validEntity is {}", validVO);
        return "test2 valid success";
    }

    @ApiOperation("单参数校验")
    @PostMapping(value = "/valid/test3")
    public String test3(@Email String email){
        log.info("email is {}", email);
        return "email valid success";
    }
}

通过 @Api注解标注需要生成接口文档，通过 @ApiOperation注解标注接口名。

同时我们给 ValidVO也加上对应的注解

@Data
@ApiModel(value = "参数校验类")
public class ValidVO {

    @ApiModelProperty("ID")
    private String id;

    @ApiModelProperty(value = "应用ID",example = "cloud")
    private String appId;

    @NotEmpty(message = "级别不能为空")
    @ApiModelProperty(value = "级别")
    private String level;

    @ApiModelProperty(value = "年龄")
    private int age;
  
    ...

}

通过 @ApiModel标注这是一个参数实体，通过 @ApiModelProperty标注字段说明。

Unable to infer base url

简单三步，我们项目就集成了Swagger接口文档，赶紧启动服务，访问 http://localhost:8080/swagger-ui.html 体验一下。

好吧，出了点小问题，不过不用慌。

出现这个问题的原因是因为我们加上了 ResponseBodyAdvice统一处理返回值/响应体，导致给Swagger的返回值也包装了一层，UI页面无法解析。可以通过 http://localhost:8080/v2/api-docs?group=SwaggerDemo观察Swagger返回的json数据。

既然知道了问题原因那就很好解决了，我们只需要在ResponseBodyAdvice处理类中只转换我们自己项目的接口即可。

@RestControllerAdvice(basePackages = "com.jianzh5.blog")
@Slf4j
public class ResponseAdvice implements ResponseBodyAdvice