Swagger - 技术栈

介绍

Swagger 是一种开源框架，用于生成、描述和调用RESTful接口的Web服务。

Swagger能够帮助开发者自动生成API文档，并且这些文档会随着代码的更新而实时更新，从而避免了传统手动维护API文档的繁琐过程。同时，Swagger还支持多种语言，并能通过Swagger UI展示易于浏览和测试的交互式API文档。

Swagger的核心功能之一是其能够将项目中的所有接口自动展示在一个页面上，并提供接口调用和测试的功能。这样后端开发者就无需为前端使用者编写专门的接口文档。当接口发生更新时，只需修改代码中的Swagger描述即可立即反映至生成的接口文档中。

Swagger包括三个主要部分：Swagger Editor用于编写OpenAPI规范，Swagger UI则负责将编写的规范呈现为交互式的API文档，而Swagger Codegen可以通过OpenAPI规范定义生成服务器存根和客户端SDK，大大简化了构建过程。这使得Swagger不仅能够提升开发效率，还能确保API的准确性和易用性。

此外，Swagger显著提升了前后端分离项目的集成和开发效率。在前后端分离的开发模式中，API成为前后端交互的桥梁，而Swagger通过自动生成和动态更新API文档，有效解决了因手动维护文档导致的信息滞后问题。

knife4j

Knife4j 是一个开源的接口文档工具，可以看作是 Swagger 的增强版，提供了更美观的界面和更多的功能。

Knife4j的前身是swagger-bootstrap-ui，随着项目的发展，为了满足更多个性化需求，开发团队在其基础上增加了后端Java代码，从而演变成了现在的Knife4j。相比于Swagger，Knife4j不仅优化了UI界面，还增强了交互体验，并且支持在线调试和多语言等功能。它适用于单体应用和微服务项目，支持Spring MVC、Spring Boot和Spring Cloud框架的集成使用。

在整合Spring Boot时，首先需要在项目中引入Knife4j的相关依赖，并创建相应的配置类来启用Knife4j。配置过程中，需要设置API文档的路径、是否启用Swagger以及Knife4j的访问路径等信息。通过这些步骤，开发者可以方便地管理和测试API文档，大大提升开发效率和文档的可读性。

常用注解

注解	说明
@Api	用在类上，例如Controller，表示对类的说明
@ApiModel	用在类上，例如entity、DTO、VO
@ApiModelProperty	用在属性上，描述属性信息
@ApiOperation	用在方法上，例如Controller的方法，说明方法的用途、作用

使用步骤

导入依赖

Maven配置：在项目的pom.xml文件中添加以下依赖：
版本兼容：确保所选的Knife4j版本与Spring Boot版本兼容。例如，对于Spring Boot 2.4.0及以上版本，建议使用Knife4j 4.0及更高版本。

XML 复制代码

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>${latest.version}</version>
</dependency>

编写配置类

创建配置类：在项目中创建一个配置类，通常命名为Knife4jConfig或SwaggerConfig。
配置Docket：在配置类中定义一个Bean来创建Docket实例，配置API的基本信息如标题、描述和版本号。

java 复制代码

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("你的包路径"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API标题")
                .description("API描述")
                .version("API版本")
                .build();
    }
}

配置Swagger信息

应用设置：在application.properties或application.yml中配置Swagger和Knife4j的相关信息。
启用Swagger和Knife4j：确保配置文件中的相关选项被正确设置以启用这些功能。

java 复制代码

# Swagger配置
swagger.enabled=true
# Knife4j配置
knife4j.swagger-ui.enabled=true
knife4j.swagger-ui.path=/doc.html

使用注解

@Api的使用：在控制器类上使用@Api注解来提供该类的说明信息。例如：

java 复制代码

@Api(tags = "用户管理模块")
public class UserController { ... }

@ApiOperation的使用：在方法上使用@ApiOperation注解来描述具体的API操作，例如：

java 复制代码

@GetMapping("/{id}")
@ApiOperation(value = "获取用户信息", notes = "根据用户id获取用户信息")
public User getUser(@PathVariable Integer id) { ... }

查看接口文档

访问文档页面：启动Spring Boot项目后，访问http://localhost:8080/doc.html（或你配置的路径）即可查看生成的API文档。

导出离线文档

支持离线文档：Knife4j支持将API文档导出为离线格式，方便在没有网络的情况下查看和分享。

通过以上步骤，你可以成功将Knife4j整合到你的Spring Boot项目中，提升API文档的质量和管理效率。