SpringBoot 整合 Swagger3.0 和 Knife4j

我高考零分!

已于 2022-05-05 10:57:15 修改

阅读量2.1k

点赞数 2

CC 4.0 BY-SA版权

分类专栏： Java 文章标签： java swagger2 spring boot

于 2021-11-23 10:00:00 首次发布

本文链接：https://blog.csdn.net/Amber_1/article/details/121470338

Java 专栏收录该内容

41 篇文章

订阅专栏

本文介绍了Knife4j这款轻量级的Swagger接口文档解决方案，包括其前身、pom.xml配置、Spring Boot集成、配置文件详解、访问地址和关键注解的使用。展示了如何通过注解自动生成详细的API文档，并提供了不同版本的访问路径。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

一、简介

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：多个请求参数。