springboot整合swagger

九转成圣

已于 2024-06-01 18:25:51 修改

阅读量1.7k

点赞数 7

文章标签： spring boot 后端 java

于 2024-03-17 09:14:30 首次发布

本文链接：https://blog.csdn.net/weixin_41883161/article/details/136504889

版权

Swagger 是一款用于 API 文档生成和测试的强大工具。通过整合 Swagger，可以自动生成 RESTful API 文档，提供 API 的详细说明，并支持在线测试接口。这对于开发、测试和维护 API 非常有帮助。本文将详细介绍如何在 Spring Boot 项目中整合 Swagger2 和 Swagger3，并展示常用的注解和配置示例。

一、整合 Swagger2

1. 添加依赖

在 Spring Boot 项目中添加 Swagger2 的依赖：

<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

创建一个配置类 Swagger2Config，用于配置 Swagger2：

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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

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

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot 测试使用 Swagger2 构建 RESTful API")
                .contact(new Contact("cookie", "http://www.baidu.com", "2118119173@qq.com"))
                .version("1.0")
                .description("用户管理 API 文档")
                .build();
    }
}

3. 访问 Swagger UI

启动项目后，访问 http://localhost:8080/swagger-ui.html 即可查看 Swagger UI，所有已配置的 API 将在此展示并可进行测试。

二、整合 Swagger3

1. 添加依赖

在 Spring Boot 项目中添加 Swagger3 的依赖：

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

2. 配置 Swagger

Swagger3 的配置基本与 Swagger2 相同，仍然使用 Swagger2Config 进行配置：

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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

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

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot 测试使用 Swagger3 构建 RESTful API")
                .contact(new Contact("cookie", "http://www.baidu.com", "2118119173@qq.com"))
                .version("1.0")
                .description("用户管理 API 文档")
                .build();
    }
}

3. 访问 Swagger UI

启动项目后，访问 http://localhost:8080/swagger-ui/index.html 即可查看 Swagger3 的 UI 界面，所有已配置的 API 将在此展示并可进行测试。

三、Swagger 常用注解

1. @Api

用于修饰整个类，描述 Controller 的作用。

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

@Api(value = "部门管理", tags = "部门管理相关接口")
@RestController
@RequestMapping("/dept")
public class DeptController {
    // 相关接口
}

2. @ApiOperation

用于描述一个类的一个方法或接口的作用。

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

@RestController
@RequestMapping("/dept")
public class DeptController {

    @ApiOperation("根据部门 ID 获取部门信息")
    @GetMapping("/{id}")
    public Dept getDeptById(@PathVariable("id") Integer id) {
        // 逻辑
        return new Dept();
    }
}

3. @ApiParam

用于描述单个参数的信息。

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

@RestController
@RequestMapping("/dept")
public class DeptController {

    @ApiOperation("根据部门 ID 删除部门")
    @DeleteMapping("/{id}")
    public String deleteDeptById(@ApiParam(value = "部门 ID", required = true) @PathVariable("id") Integer id) {
        // 逻辑
        return "删除成功";
    }
}

4. @ApiModel

用于实体类，描述对象的作用。

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("部门实体类")
public class Dept {
    @ApiModelProperty(value = "部门编号", example = "100")
    private Integer deptno;

    @ApiModelProperty("部门名称")
    private String dname;

    @ApiModelProperty("部门所在地")
    private String loc;

    // Getters and Setters
}

5. @ApiModelProperty

用于描述实体类中字段的作用。

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("部门实体类")
public class Dept {
    @ApiModelProperty(value = "部门编号", example = "100")
    private Integer deptno;

    @ApiModelProperty("部门名称")
    private String dname;

    @ApiModelProperty("部门所在地")
    private String loc;

    // Getters and Setters
}

6. @ApiResponse 和 @ApiResponses

用于描述 HTTP 响应的信息。

import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/dept")
public class DeptController {

    @ApiOperation("根据部门 ID 获取部门信息")
    @ApiResponses({
        @ApiResponse(code = 200, message = "成功，返回部门信息"),
        @ApiResponse(code = 400, message = "请求参数有误"),
        @ApiResponse(code = 404, message = "未找到指定部门")
    })
    @GetMapping("/{id}")
    public Dept getDeptById(@PathVariable("id") Integer id) {
        // 逻辑
        return new Dept();
    }
}

7. @ApiImplicitParam 和 @ApiImplicitParams

用于描述请求参数的信息，适用于多个参数的情况。

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

@RestController
@RequestMapping("/dept")
public class DeptController {

    @ApiOperation("根据地址和名字查询部门")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "dname", value = "部门名称", example = "开发部"),
        @ApiImplicitParam(name = "loc", value = "部门地址", example = "北京")
    })
    @GetMapping("/search")
    public Dept getDeptByDnameAndLoc(@RequestParam("dname") String dname, @RequestParam("loc") String loc) {
        // 逻辑
        return new Dept();
    }
}

四、优化配置和最佳实践

1. 分环境配置 Swagger

在实际开发中，可以根据不同的环境来配置 Swagger 是否启用。通常在开发和测试环境中启用，在生产环境中禁用。可以通过 Spring 的 @Profile 注解来实现。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
@Profile({"dev", "test"})
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.hello.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot 测试使用 Swagger 构建 RESTful API")
                .contact(new Contact("cookie", "http://www.baidu.com", "2118119173@qq.com"))
                .version("1.0")
                .description("用户管理 API 文档")
                .build();
    }
}

2. 自定义 Swagger UI 样式

Swagger UI 提供了一些自定义的选项，可以通过添加 swagger-ui 的配置文件来实现，比如更改页面标题、添加公司 Logo 等。

在 src/main/resources/static 下创建 swagger-ui.html 并进行自定义：

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>API 文档</title>
    <link rel="icon" type="image/png" href="https://example.com/logo.png">
    <link href="https://fonts.googleapis.com/css?family=Open+Sans:400,700|Source+Code+Pro:400,700" rel="stylesheet">
    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui.css">
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui-bundle.js"></script>
<script>
    window.onload = function() {
        const ui = SwaggerUIBundle({
            url: "/v2/api-docs",
            dom_id: '#swagger-ui',
            presets: [
                SwaggerUIBundle.presets.apis,
                SwaggerUIBundle.SwaggerUIStandalonePreset
            ],
            layout: "BaseLayout",
            deepLinking: true,
            docExpansion: "none"
        });
        window.ui = ui;
    };
</script>
</body>
</html>

3. 使用 Swagger 扩展注解

Swagger 还提供了一些扩展注解，用于更加详细地描述 API，比如 @ApiModelProperty 的 hidden 属性用于隐藏某些字段，@ApiResponses 的 examples 属性用于提供示例响应等。

@ApiModel("用户实体类")
public class User {
    @ApiModelProperty(value = "用户 ID", example = "1", hidden = true)
    private Long id;

    @ApiModelProperty(value = "用户名", example = "张三")
    private String username;

    @ApiModelProperty(value = "密码", example = "123456", hidden = true)
    private String password;

    // Getters and Setters
}

@ApiOperation("根据用户 ID 获取用户信息")
@ApiResponses({
    @ApiResponse(code = 200, message = "成功", response = User.class),
    @ApiResponse(code = 404, message = "未找到用户", examples = @Example(@ExampleProperty(mediaType = "application/json", value = "{ \"message\": \"未找到用户\" }")))
})
@GetMapping("/{id}")
public User getUserById(@PathVariable("id") Long id) {
    // 逻辑
    return new User();
}

总结

通过以上内容的介绍，您可以在 Spring Boot 项目中轻松整合 Swagger2 和 Swagger3，并掌握 Swagger 常用的注解和配置技巧。在实际项目中，使用 Swagger 生成 API 文档不仅能提高开发效率，还能使得 API 的使用更加规范和透明。希望本文能对您有所帮助，祝您在 API 开发和维护过程中更加顺利。

完整的代码示例和更多详细信息可以参考 Swagger 官方文档和 Springfox 文档。