使用SpringBoot集成Swagger3.0实现在线接口文档功能

概述

Swagger 3.0 是一个开源的框架，用于设计、构建和文档化 RESTful API。它允许开发者定义 API 规范，包括请求、响应、端点等信息，并生成交互式 API 文档。Knife4j 则是 Swagger 的一个增强版本，提供了更美观和功能丰富的界面。

集成步骤

1、添加依赖

在 Spring Boot 项目的 pom.xml 文件中添加 Swagger 和 Knife4j 的依赖：

<!-- Swagger3 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

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

2、配置 Swagger

创建一个配置类来配置 Swagger：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
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 api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())
                .build();
    }
}

• 这段代码启用 Swagger，并配置它扫描哪些包中的类来生成 API 文档。

• 配置 Knife4j

  Knife4j 可以根据 Swagger 生成的文档提供更美观和功能丰富的界面，一般情况下无需额外配置。

• 访问 Swagger UI

  启动 Spring Boot 应用程序后，访问以下 URL 查看生成的 API 文档：

http://localhost:8080/swagger-ui/index.html

如果使用 Knife4j，可以访问：

http://localhost:8080/doc.html

示例代码

假设有一个简单的控制器类 UserController，用来管理用户信息：

package com.example.controller;

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

@RestController
@RequestMapping("/api/users")
@Api(tags = "用户管理", description = "用户增删改查接口")
public class UserController {

    @GetMapping("/{id}")
    @ApiOperation("根据用户ID获取用户信息")
    public String getUser(@PathVariable Long id) {
        return "User information for id " + id;
    }

    @PostMapping("/")
    @ApiOperation("添加用户")
    public String addUser(@RequestBody String user) {
        return "User added: " + user;
    }

    @PutMapping("/{id}")
    @ApiOperation("更新用户信息")
    public String updateUser(@PathVariable Long id, @RequestBody String user) {
        return "User information updated for id " + id + ": " + user;
    }

    @DeleteMapping("/{id}")
    @ApiOperation("删除用户")
    public String deleteUser(@PathVariable Long id) {
        return "User deleted for id " + id;
    }
}

总结

集成 Swagger 3.0 和 Knife4j 到 Spring Boot 项目中，可以快速方便地生成和管理 API 文档，提升 API 的可读性和开发效率。通过上述步骤和示例代码，可以在你的项目中轻松实现这一目标。