# seaboot-openapi

**Repository Path**: seaboot/seaboot-openapi

## Basic Information

- **Project Name**: seaboot-openapi
- **Description**: 基于springdoc，提供更好的openapi，支持将系统接口直接导入到postman中。
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 6
- **Forks**: 1
- **Created**: 2020-11-03
- **Last Updated**: 2025-10-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Swagger

## README

# seaboot-openapi

如果项目中存在大量的自定义接口、注解，会导致 swagger 的扫描不彻底，效果不尽如人意。
这个框架对 spring-doc 进行功能扩展，可以直接对接 postman。

兼容 spring5 版本，不支持 restful 和其它很新的代码。

#### 基本原理

postman 有一个接口导出功能，可以将接口文档打包成 json，
只要我们把后台接口，打包成这种格式，就能被 postman 识别。

#### 介绍

spring-doc 如何使用，现在仍然怎么用，我们并未改动原先的任何设计，只是用不同的方式，解析系统中存在的接口。

 1. 接口文档采用 postman 规范（Postman Collection Format v2.1.0），
    本质上就是一个 json，把系统接口打包成指定的 json 格式，就能在 postman 上使用；
 2. spring-doc 的功能仍然可用，我们也期待 spring-doc 更优秀的版本，
    如果将来 spring-doc 达到我们想要的效果，仍然可以直接切换回 spring-doc；
 3. 支持部分 hibernate-validate，postman 操作面板空间有限，只能写关键内容；
 4. 关键节点的代码扫描，都有接口定义，如果默认的代码不满足使用，仍然可以选择自定义。

#### 工程目录

项目中还有不少 README.md 文件，有目录内容的详细介绍。

```text
|-- openapi 扫描程序
    |-- base         ControllerInfo、MethodInfo两个基础工具类
    |-- item         将 request 和 response 合并
    |-- request      请求方式扫描（url、参数等）
    |-- response     数据样例扫描（完成这个设置，postman 上能看到样例数据）
|-- postman 这个包的代码不要改，就是根据 postman-collection 抽象出来的对象
```

    
#### 安装教程

写一个主函数，将输出内容保存成 json，之后导入到 postman。

```java
/**
 * @author Mr.css
 * @version 2022-10-21 9:52
 */
public class WorkTaskExample {

   public static void main(String[] args) {
      Environment environment = new Environment();
      environment.setOriginalUrl("http://localhost:8081/sea");

      Postman postman = PostmanBuilder.create()
              .setEnvironment(environment)
              .setExclusive("cn.seaboot.admin.*.web.page;org.springframework")
              .searchApi(AppInfoCtrl.class)
              .build();

      System.out.println(FastJsonUtils.toJSONString(postman));
   }
}
```

#### 注解的使用（与 spring-doc 一致）

本框架未改动 spring-doc 的原有的内容，spring-doc 原始功能都是可以用的；
获取 spring-doc 接口文档：http://xxxx:xxx/项目名/v3/api-docs。

注意：想启用 swagger 界面，需要将 maven 依赖调整为：springdoc-openapi-ui。

```java

import cn.seaboot.web.validate.Update;
import io.swagger.v3.oas.annotations.media.Schema;
import org.hibernate.validator.constraints.Length;

import javax.validation.constraints.NotNull;
import java.io.Serializable;
import java.time.LocalDateTime;

/**
 * POJO
 * App信息表 [t_sys_app_info]
 * <p>
 *
 * @author Mr.css on 2018/6/20.
 */
@Schema(description = "App信息表 [t_sys_app_info] 实体类")
public class SysAppInfo implements Serializable {
   @java.io.Serial
   private static final long serialVersionUID = 7202050212014606841L;

   /**
    * ID
    */
   @NotNull(groups = Update.class)
   @Schema(description = "ID")
   private Long id;
   /**
    * 应用名称
    */
   @Length(max = 64)
   @Schema(description = "应用名称")
   private String appName;
   /**
    * 版本号
    */
   @Length(max = 10)
   @Schema(description = "版本号")
   private String version;
   /**
    * 创建日期
    */
   @Schema(description = "创建日期")
   private LocalDateTime gmtCreate;
   /**
    * 更新日期
    */
   @Schema(description = "更新日期")
   private LocalDateTime gmtModified;

   //下列省略getter/setter
}
```

````java

/**
 * 系统APP文件 [t_sys_app_info] - Controller
 * <p>
 *
 * @author Mr.css on 2018/6/20.
 * @version 1.0.0
 */
@Controller
@RequestMapping("sys/app")
@Tag(name = "系统APP文件 [t_sys_app_info] 管理")
public class AppInfoCtrl {

    @Resource
    AppInfoService appInfoService;

    @Resource
    UploadConstant uploadConstant;

    /**
     * 增
     *
     * @param pojo pojo
     * @return affected rows
     */
    @ResponseBody
    @Operation(description = "系统APP文件 [t_sys_app_info] 增")
    @RequestMapping(value = "info", method = RequestMethod.POST)
    public int saveInfo(@RequestParam @Validated SysAppInfo pojo,
                        @RequestParam(required = false) MultipartFile file) throws IOException {
        String path = UploadFactory.writer(uploadConstant.getApp()).write(file);
        pojo.setAppPath(path);
        return appInfoService.insert(pojo);
    }

    /**
     * 删
     *
     * @param id id
     * @return affected rows
     */
    @ResponseBody
    @Operation(description = "系统APP文件 [t_sys_app_info] 删")
    @RequestMapping(value = "info", method = RequestMethod.DELETE)
    public int deleteInfo(@Params Long id) {
        return appInfoService.deleteById(id);
    }

    /**
     * 查
     *
     * @param id id
     * @return pojo
     */
    @ResponseBody
    @Operation(description = "系统APP文件 [t_sys_app_info] 查")
    @RequestMapping(value = "info", method = RequestMethod.GET)
    public SysAppInfo queryById(@Params long id) {
        return appInfoService.queryById(id);
    }

    /**
     * 改
     *
     * @param pojo pojo
     * @return affected rows
     */
    @ResponseBody
    @Operation(description = "系统APP文件 [t_sys_app_info] 改")
    @RequestMapping(value = "info", method = RequestMethod.PUT)
    public int updateInfo(@RequestParam @Validated(Update.class) SysAppInfo pojo,
                          @RequestParam(required = false) MultipartFile file) throws IOException {
        SysAppInfo old = appInfoService.queryById(pojo.getId());
        String path = UploadFactory.writer(uploadConstant.getApp()).overwrite(old.getAppPath(), file);
        pojo.setAppPath(path);
        return appInfoService.updateById(pojo);
    }

    /**
     * 查列表
     *
     * @param page   页
     * @param limit  行
     * @param params 参数
     * @return PageInfo
     */
    @ResponseBody
    @Operation(description = "系统APP文件 [t_sys_app_info] 列表查询",
        parameters = {
            @Parameter(name = "page", description = "页号"),
            @Parameter(name = "limit", description = "行数")
        })
    @RequestMapping(value = "page", method = RequestMethod.GET)
    public PageInfo<Map<String, Object>> queryPage(
        @Params(value = "page", defaultValue = AppConstant.PAGE) Integer page,
        @Params(value = "limit", defaultValue = AppConstant.LIMIT) Integer limit,
        @RequestParam Map<String, Object> params) {
        PageHelper.startPage(page, limit);
        List<Map<String, Object>> l = appInfoService.queryList(params);
        return new PageInfo<>(l);
    }
}

````

#### 项目依赖

1. 这个项目用到了我的工具包，common 依赖下载地址：https://gitee.com/seaboot/common.git

2. spring-doc 依赖用的是 swagger-annotations，也就是说我们只用到了注解部分，如果想要 spring-doc 其它东西，
   可以将 swagger-annotations 替换成 springdoc-openapi-ui（包含界面），或者 springdoc-openapi-core（核心部分）。

#### 版本说明

2020/11/07：增加对 MultipartFile 参数的支持；

2020/11/11：postman 的字段描述是一段字符串，字段过长页面会非常难看，
对 hibernate-validate 的支持上，只展示了 “是否必填” 和 “字段长度要求”；
（校验相关内容，考虑将代码退回到这个版本）

2020/11/22：允许忽略一部分的参数，解析注解中的 hidden 值；

2020/11/22：忽略 @SessionAttribute、@RequestHeader 等注解标注的参数；

2020/04/01：增加 Response 数据说明，1.0.0版本基本完成；

2020/04/01：1.0.1版本，调整代码算法，减少Java反射的使用次数，重新调整代码结构，
代码可读性更高，也更容易扩展新的功能，每个类的代码一般不超过300行，拆分不同的功能组件，可随时重写替换；

2021/06/21：解决bug：无法解析 @RequestMapping 为缺省值的情况；

2022/01/21：解决bug：忽略对象中的 static 字段；

2022/02/12：调整包结构，代码结构更加清晰，新增一个接口 ApiAnalyzer，允许最大限度的自定义API扫描代码；

2022/10/25：解决Java反射无法解析参数名问题，优化了 Java 反射部分的代码，使用方式上不变；

2022/10/25：重新设计了对 hibernate-validator 的兼容代码，想兼容 hibernate-validator8，
但是这个版本的包名有变化，需要进一步优化；（未实现）

2023/09/18：项目拆包，分离出 postman-api，为后续代码升级做准备；
后续版本，考虑将分析出来的数据，直接持久化到数据库中，允许程序员进行二次编程。

#### 参与贡献

1.  Mr.css

#### postman接口规范

https://schema.getpostman.com/json/collection/v2.1.0/docs/index.html