Swagger 和 Knife4j 的超有趣使用指南

在 Java 后端开发的江湖里，接口就像是大侠们的武功秘籍，每个接口都有独特的 "招式" 和 "威力"。但要是没有合适的 "武功宝典" 记录，这些秘籍就容易失传，接口也会变得难以理解和使用。今天，咱就来聊聊两款超厉害的 "武功宝典"------Swagger 和 Knife4j，它们能让你的接口开发和文档管理变得轻松又有趣！

一、Swagger：接口文档界的 "超级英雄"

Swagger 可是接口文档界的 "扛把子"，就像超级英雄一样，拥有强大的 "超能力"，能自动生成接口文档。

（一）Swagger 的神奇之处

想象一下，你写了一堆接口，要是手动写文档，那不得写到怀疑人生？Swagger 就不一样啦，它能根据你的代码，像变魔术一样，自动生成一份详细的接口文档。里面包含了接口的地址、请求方式、参数、响应结果等等，简直比你自己写的还全面！

（二）如何在项目中引入 Swagger

引入 Swagger 就像给你的项目找了个 "贴心小助手"，步骤也不难：

添加依赖：在你的pom.xml文件里，加上 Swagger 的依赖，就像给大侠准备好趁手的兵器。

xml 复制代码

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

配置 Swagger：在项目里创建一个配置类，告诉 Swagger 哪些接口需要生成文档，就像告诉小助手工作范围。

typescript 复制代码

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
              .apiInfo(apiInfo())
              .select()
                // 这里指定Controller扫描包路径
              .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
              .paths(PathSelectors.any())
              .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
              .title("Swagger示例")
              .description("Swagger在Java项目中的使用示例")
              .version("1.0")
              .build();
    }
}

启动项目，查看文档 ：启动项目后，访问http://localhost:8080/swagger-ui.html，你就会看到 Swagger 生成的超酷接口文档啦！

二、Knife4j：Swagger 的 "超级皮肤"

Knife4j 就像是 Swagger 的 "超级皮肤"，不仅保留了 Swagger 的强大功能，还在界面和功能上进行了升级，让你使用起来更爽！

（一）Knife4j 的独特魅力

Knife4j 的界面更简洁美观，操作也更方便。就像给你的爱车换了个超酷炫的涂装，不仅好看，还更好开。而且它还支持在线测试接口，就像给你的武功秘籍加上了实战演练功能，让你能随时验证接口的正确性。

（二）如何在项目中引入 Knife4j

引入 Knife4j 也很简单，就像给你的项目换个新皮肤：

添加依赖：在pom.xml里添加 Knife4j 的依赖。

xml 复制代码

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

配置 Knife4j：和 Swagger 类似，创建一个配置类。

kotlin 复制代码

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
@Configuration
@EnableSwagger2WebMvc
@EnableKnife4j
public class Knife4jConfiguration {
    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
              .apiInfo(apiInfo())
                // 分组名称
              .groupName("2.X版本")
              .select()
                // 这里指定Controller扫描包路径
              .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
              .paths(PathSelectors.any())
              .build();
        return docket;
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
              .title("Knife4j示例")
              .description("Knife4j在Java项目中的使用示例")
              .version("1.0")
              .build();
    }
}

启动项目，体验新界面 ：启动项目后，访问http://localhost:8080/doc.html，你会发现 Knife4j 的界面比 Swagger 更酷炫，功能也更强大！

三、总结

Swagger 和 Knife4j 就像是 Java 后端开发的 "黄金搭档"，一个负责生成接口文档，一个负责优化文档体验。有了它们，你的接口开发和文档管理就像开了挂一样轻松。还等什么呢？赶紧在你的项目里试试吧，让你的接口开发之路更加顺畅！