【SpringBoot】Swagger 接口工具

文章目录

• 目标
• Swagger简介
• • 前后端分离
  • 产生的问题
  • 解决方案
  • Swagger
• SpringBoot集成Swagger
• • 项目驱动
  • 具体流程
  • • 导入依赖`springdoc-openapi-starter-webmvc-ui`
    • 配置swagger的config
    • 分组：定义自定义模块和扫描路径
    • [2.0（Docket） 和 3.0 的区别](#2.0（Docket） 和 3.0 的区别)
    • 实体类的扫描
    • swagger的其他配置
  • 总结

目标

• 了解作用
• 了解前后端分离
• 在SpringBoot 中集成

Swagger简介

前后端分离

典型：Vue

SpringBoot+Vue/React 经典 ；

• 后端时代：前端管理 只是静态页面，后期引申为JSP
• 前后端分离：
  • 后端：控制层，服务层，数据访问层
  • 前端：控制层，视图层

前后端通过api进行交互

前后端相对对立，松耦合度

前后端部署到不同的服务器上，与微信小程序同理

产生的问题

前后端集成，前端或者后端无法做到"及时协商，尽早解决"，最终导致问题集中爆发

解决方案

• 定义一个 schema 计划，及时跟踪降低风险；
• 制定word开发计划文档；
• 前期测试后端接口 使用 postman，依赖于外部管理；
• Swagger出现，一个api框架

Swagger

• 一个比较流行的API框架；
• Restful API文档在线自动生成器，API和API定义同步更新；
• 直接运行，在线测试API
• 支持多种语言
• 官网： https://swagger.io/
• 中文网站： https://swagger.org.cn/docs/
• 替代：ApiFox

SpringBoot集成Swagger

项目驱动

1. 新建一个SpringBoot的web项目；
2. 导入依赖：SpringBoot-web、Swagger、Swagger-ui

Spring Boot 3.5.4 版本，由于 Springfox（传统 Swagger 实现）已不兼容 Spring Boot 3.x，必须改用 SpringDoc OpenAPI（支持 OpenAPI 3.0 规范）；

3. Spring Boot 2.*时代的依赖

在 Spring Boot 3.5.4 中集成 Swagger 需要使用 SpringDoc OpenAPI （替代已停止维护的 Springfox），之前使用的Docket也已经被废止，换成了GroupedOpenApi和 OpenAPIBean的组合

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>3.0.0</version>
</dependency>

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>3.0.0</version>
</dependency>

4. 新使用的依赖是 springdoc-openapi-starter-webmvc-ui，不需要使用Swagger-ui
5. 编写一个Hello程序，测试后开始swagger学习；

具体流程

导入依赖springdoc-openapi-starter-webmvc-ui

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.5.0</version> <!-- 兼容 Spring Boot 3.5.4 的最新稳定版 -->
</dependency>

配置swagger的config

1. 编写Config配置文件，配置swagger的内容显示

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("新接口网页")
                        .version("2.0")
                        .description("基于 OpenAPI 3.0 的配置"));
    }
}

2. 项目启动成功

3. 访问swagger UI页面 [http://localhost:8080/swagger-ui/index.html](http://localhost:8080/swagger-ui/index.html),页面显示正常;

4. 访问http://localhost:8080/v3/api-docs ，查看完整的 OpenAPI 3.0 规范 JSON;

5. 对比我们的Controller请求,内容显示无误

分组：定义自定义模块和扫描路径

1. 注入GroupedOpenApi，显示我们自定义模块和分组扫描的路径

@Bean
public GroupedOpenApi indexApi() {
    return GroupedOpenApi.builder()
            .group("默认")
            .pathsToMatch("/**") // 匹配接口路径
            .build();
}

@Bean
public GroupedOpenApi userApi() {
    return GroupedOpenApi.builder()
            .group("用户模块")
            .pathsToMatch("/api/users/**") // 匹配接口路径
            .build();
}

2. 页面显示，因为使用的@RequestMapping，所以所有的请求都显示了；

2.0（Docket） 和 3.0 的区别

实体类的扫描

1. 编写Controller，实体类，查看swagger-ui的页面

@RestController
public class HelloController {

    @PostMapping("/hello")
    public String hello() {
        return "Greetings from Spring Boot!";
    }

    @GetMapping("/user")
    public User userList() {
        return new User();
    }
}

public class User {

    private String name;
    private String password;
    private String sex;

}

2. 修改实体类，加上@Schema，添加描述信息

package com.demo.pojo;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

@Data
@Schema(description = "用户信息")
public class User {

    @Schema(description = "用户名称")
    private String name;
    @Schema(description = "用户密码")
    private String password;
    @Schema(description = "用户性别")
    private String sex;


    public User() {

    }

    public User(String name, String password, String sex) {
        this.name = name;
        this.password = password;
        this.sex = sex;
    }
}

3. 测试页面，内容显示，方便前后端互相分工操作开发内容；

swagger的其他配置

1. Java配置，同上，使用@Bean的方式注入，配置一个@Conguration；
2. yaml配置；

springdoc:
  api-docs:
    enabled: true # 配置swagger是否启动
    path: /v3/api-docs # 规范 JSON的资源路径
  swagger-ui:
    path: /swagger-ui.html 
  packages-to-scan:  # 基础包扫描
    - com.example.controller 
    - com.example.api
  paths-to-match:    # 路径模式匹配
    - /api/**
    - /public/**
  paths-to-exclude:  # 路径排除
    - /internal/**

3. 判断当前的环境是什么，如果和提前定义的swagger环境相同，则为true，开启swagger，反则关闭。

4. Swagger测试，Execute根据输入的Parameter进行测试，会直接相应之后的信息，类比Postman思考，差不多

总结

1. 可以通过Swagger对接口和属性等内容添加注释；
2. 接口文档会根据项目内容自动更新；
3. 可以直接启动项目进行在线测试；

Swagger的使用很方便，需要注意 在正式使用发布的时候一定要关闭Swagger，安全，节能，高效。

apifox感觉也很不错 ，https://apifox.com/