SpringBoot+Swagger打造美观API文档的实战指南_开发_开发者

导语

在现代 Web 开发中，API 文档是开发者和团队协作的重要组成部分。Swagger 作为一款强大的 API 文档生成工具，能够自动生成直观、可交互的接口文档，提升开发效率。本文将详细介绍如何在 Spring Boot 2 和 Spring Boot 3 中集成 Swagger，并展示多种接口文档风格，帮助开发者选择适合自己项目的展示方式。

一、Swagger 简介

Swagger 是一个开源工具，用于生成、描述和可视化 RESTful API。它不仅能自动生成 API 文档，还提供交互式界面，方便开发者测试和调试接口。Swagger 与 Spring Boot 集成后，可以轻松管理和展示项目的 API。

二、Spring Boot 2 集成 Swagger

Spring Boot 2 中，常用的 Swagger 集成方案是基于 Springfox 库。以下是具体步骤：

1. 添加依赖

在项目的 pom.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>

2. 配置 Swagger

创建一个配置类，例如 SwaggerConfig.Java，启用 Swagger 并定义文档的基本信息：

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;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 指定扫描的包
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot 2 Swagger API")
                .description("API documentation for Spring Boot 2 project")
                .version("1.0.0")
                .build();
    }
}

3. 访问 Swagger UI

启动 Spring Boot 应用后，打开浏览器访问 http://localhost:8080/swagger-ui.html，即可看到生成的 API 文档界面。

三、Spring Boot 3 集成 Swagger

Spring Boot 3 中，由于 Springfox 已不再积极维护，推荐使用 Springdoc OpenAPI 库。它与 Spring Boot 3 的新特性（如 Jakarta EE）兼容，且配置更简单。

1. 添加依赖

在 pom.xml 中添加 Springdoc OpenAPI 的依赖：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.9</version>
</dependency>

2. 配置 Swagger

Springdoc 默认自动启用 Swagger UI，无需额外配置。但可以通过 application.properties 或 application.yml 自定义路径和行为，例如：

# 自定义 Swagger UI 路径
springdoc.swagger-ui.path=/swagger-ui.html
# 自定义 API 文档 jsON 路径
springdoc.api-docs.path=/v3/api-docs

3. 访问 Swagger UI

启动应用后，访问 http://localhost:8080/swagger-ui.html，即可查看 API 文档。

四、多种接口文档风格展示

Swagger 提供了多种 UI 风格，开发者可以根据需求选择合适的展示方式。以下是几种常见的风格及其配置方法：

1. 默认 Swagger UI

Swagger UI 是最常用的风python格，提供交互式界面，支持 API 测试。Spring Boot 2 和 3 默认集成后即可使用：

Spring Boot 2：http://localhost:8080/swagger-ui.html
Spring Boot 3：http://localhost:8080/swagger-ui.html

2. Redoc

Redoc 是一个简洁、美观的静态文档展示工具，适合生成静态 API 文档。在 Spring Boot 3 中使用 Springdoc 配置：

在 application.properties 中添加：

# 禁用默认 Swagger UI
springdoc.swagger-ui.enabled=false
# 启用 Redoc
springdoc.redoc.enabled=true

访问 http://localhost:8080/redoc，即可查看 Redoc 风格的文档。

3. Knife4j

Knife4j 是 Swagger 的增强版，提供更丰富的功能和更友好的界面，支持 Spring Boot 2 和 3。

在 Spring Boot 2 中集成 Knife4j

添加依赖：

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

修改配置类：

@Configuration
@EnableSwagger2
@EnableKnife4j
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot 2 Knife4j API")
                .description("API documentation with Knife4j")
                .version("1.0.0")
                .build();
    }
}

访问 http://localhost:8080/doc.html，即可体验 Knife4j 界面。

在 Spring Boot 3 中集成 Knife4j

添加依赖：

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

无需额外配置，启动应用后访问 http://localhost:8080/doc.html。

五、实战示例

以下是一个简单的 Spring Boot 项目示例，展示如何使用 Swagger 注解生成详细的 API 文档。

1. 创建控制器

创建一个简单的 REST 控制器：

import org.springframework.web.bind.annotation.*;
import java.util.*;

@RestController
@RequestMapping("/api")
public class UserController {
    @GetMapping("/users")
    public List<String> getUsers() {
        return Arrays.asList("Alice", "Bob");
    }

    @PostMapping("/users")
    public String createUser(@RequestBody String user) {
        return "Created: " + user;
    }
}

2. 添加 Swagger 注解

为控制器和方法添加注解，提供更详细的 API 描述：

Spring Boot 2（Springfox）

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import java.util.*;

@Api(tags = "User API")
@RestController
@RequestMapping("/api")
public class UserController {
    @ApiOperation(value = "获取所有用户", notes = "返回用户列表")
    @GetMapping("/users")
    public List<String> getUsers() {
        return Arrays.asList("Alice", "Bob");
    }

    @ApiOperation(value = "创建新用户", notes = "创建并返回新用户")
    @PostMapping("/users")
    public String createUser(@RequestBody String user) {
        return "Created: " + user;
    }
}

Spring Boot 3（Springdoc）

import io.swagger.v3.oas.annotations.Oppythoneration;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;
import java.util.*;

@Tag(name = "User API")
@RestController
@RequestMapping("/api")
public class UserController {
    @Operation(summary = "获取所有用户", description = "返回用户列表")
    @GetMapping("/users")
    public List<String> getUsers() {
        return Arrays.asList("Alice", "Bob");
    }

    @Operation(summary = "创建新用户", description = "创建并返回新用户")
    @PostMapping("/users")
    public String createUser(@RequestBody String user) {
        return "Created: " + user;
    }
}

3. 访问和测试

启动应用后，访问对应的 Swagger UI 或 Knife4j 地址（www.devze.com如 http://localhost:8080/swagger-ui.html 或 http://localhost:8080/doc.html），即可查看并测试 API。

六、总结

本文介绍了在 Spring Boot 2 和 Spring Boot 3 中集成 Swagger 的实战步骤：

Spring Boot 2 使用 Springfox Swagger，配置简单但维护较少。
Spring Boot 3 推荐 Springdoc OpenAPI，与新版本兼容且功能强大。

同时展示了多种接口文档风格：

Swagger UI：交互性强，适合开发和调试。
Redoc：简洁美观，适合静态文档。
Knife4j：功能丰富，体验更优。

通过实战示例，开发者可以快速上手并将 Swagger 应用到自己的项目中，提升 API 管理的效率和质量。

到此这篇关于SpringBoot+Swaggerpython打造美观API文档的实战指南的文章就介绍到这了,更多相关SpringBoo编程客栈t Swagger构建API文档内容请搜索编程客栈(www.devze.com)以前的文章或继续浏览下面的相关文章希望大家以后多多支持编程客栈(www.devze.com)！

SpringBoot+Swagger打造美观API文档的实战指南

目录

导语

一、Swagger 简介

二、Spring Boot 2 集成 Swagger

1. 添加依赖

2. 配置 Swagger

3. 访问 Swagger UI

三、Spring Boot 3 集成 Swagger

1. 添加依赖

2. 配置 Swagger

3. 访问 Swagger UI

四、多种接口文档风格展示

1. 默认 Swagger UI

2. Redoc

3. Knife4j

五、实战示例

1. 创建控制器

2. 添加 Swagger 注解

3. 访问和测试

六、总结

精彩评论

关注公众号

热门标签

图文推荐

SpringBoot+Swagger打造美观API文档的实战指南

目录

导语

一、Swagger 简介

二、Spring Boot 2 集成 Swagger

1. 添加依赖

2. 配置 Swagger

3. 访问 Swagger UI

三、Spring Boot 3 集成 Swagger

1. 添加依赖

2. 配置 Swagger

3. 访问 Swagger UI

四、多种接口文档风格展示

1. 默认 Swagger UI

2. Redoc

3. Knife4j

五、实战示例

1. 创建控制器

2. 添加 Swagger 注解

3. 访问和测试

六、总结

更多 开发 相关资讯：

精彩评论

关注公众号

热门标签

图文推荐

更多开发相关资讯：