SpringBoot 整合 Swagger3.0 和 Knife4j

一、简介

  Knife4j的前身是swagger-bootstrap-ui,取名knife4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍,更名也是希望把她做成一个为Swagger接口文档服务的通用性解决方案,不仅仅只是专注于前端Ui前端。

二、pom.xml

<!-- knife4j 3.0.2 相关依赖 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.2</version>
</dependency>

 三、配置文件

@Configuration
@EnableSwagger2    //开启 Swagger2
@EnableOpenApi     //开启 Swagger3，可以不写
@EnableKnife4j     //开启 knife4j，可以不写
public class Knife4jConfiguration {
    @Bean(value = "defaultApi3")
    public Docket defaultApi3() {
        
        // Swagger 2 使用的是：DocumentationType.SWAGGER_2
		// Swagger 3 使用的是：DocumentationType.OAS_30
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                // 定义是否开启swagger，false为关闭，可以通过变量控制
				.enable(true)
                .apiInfo(new ApiInfoBuilder()
                        .title("XXX服务平台Api接口文档")
                        .description("XXX服务平台Api接口文档")
                        .termsOfServiceUrl("http://127.0.0.1:8080/login")
                        .contact(new Contact("作者", "地址", "邮箱或联系方式"))
                        .version("1.0")
                        .build())
                //分组名称
                .groupName("XXX服务平台")
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                //这里指定Controller扫描包路径
                //.apis(RequestHandlerSelectors.basePackage("com.chy.**.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}

四、接口文档访问地址

knife4j 访问地址：http://localhost:8080/doc.html
Swagger2.0访问地址：http://localhost:8080/swagger-ui.html
Swagger3.0访问地址：http://localhost:8080/swagger-ui/index.html

五、注解说明

通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

@Api：修饰整个类，描述Controller的作用。
@ApiOperation：描述一个类的一个方法，或者说一个接口。
@ApiParam：单个参数描述。
@ApiModel：描述接收参数的实体对象。
@ApiProperty：用对象接收参数时，描述对象的一个字段。
@ApiResponse：HTTP响应其中1个描述。
@ApiResponses：HTTP响应整体描述。
@ApiIgnore：使用该注解忽略这个API。
@ApiError ：发生错误返回的信息。
@ApiImplicitParam：一个请求参数。
@ApiImplicitParams：多个请求参数。