# seaboot-openapi

**Repository Path**: yourkeychen/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**: 0
- **Forks**: 1
- **Created**: 2022-05-04
- **Last Updated**: 2022-05-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: API

## README

# seaboot-openapi

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

#### 介绍

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

    1、接口文档采用postman规范（Postman Collection Format v2.1.0），
       可以直接对接postman；
    2、spring-doc的功能仍然可用，期待spring-doc更优秀的版本，
       如果将来spring-doc达到我们想要的效果，仍然可以直接切换回spring-doc；
    3、支持hibernate-validate；
    4、我们定义了许多接口，用于扫描代码中的注解，每一个接口都有默认实现，
       如果不满足使用，仍然可以重新定义这些代码。

2021/07/08:

    这个版本的特色，从代码中分离出两个工具类：ControllerInfo，MethodInfo；
    Controller有非常多缺省值，一次性全面地解析系统，代码过于冗长；
    这两个工具类会初步解析系统，扫描出一些较为基础的信息，通过这些信息，可以加工出很多有用的东西，
    比如：制作接口权限配置（扫描全部Url），导出Excel格式的接口文档等等……
    
```java
   class Test{
       public static void main(String[] args){
          ControllerInfo controllerInfo = new ControllerInfo(clazz);
          List<MethodInfo> methods = controllerInfo.getMethodInfos();
       }
   }
```
    
#### 安装教程

注解的用法与spring-doc完全一致，只需要提供一个额外的Controller，用于获取系统中的接口扫描数据。

1. 导入maven依赖。
2. 编写一个Controller。
```java

/**
 * @author Mr.css
 * @date 2020-10-09 21:55
 */
@Controller
@RequestMapping("sys")
public class CoreCtrl {
    /**
     * 获取系统参数
     *
     * @return list
     */
    @ResponseBody
    @RequestMapping(value = "api", method = RequestMethod.GET)
    public Postman api() {
        PostmanConfiguration configuration = new PostmanConfiguration();
		//接口文档的名称
        configuration.setApiName("接口文档");
		//忽略的包名（按照startWith进行比较）
        configuration.setExclusive("cn.seaboot.admin.ctrl.page");
		//项目根路径
        configuration.setUrl("http://localhost:8081/sea");
		//扫描、构建接口数据
        return PostmanBuilder.create(configuration)
            //Spring上下文，按照自己的项目调整
            .searchItem(SpringContext.getApplicationContext())
            .build();
    }
}

```
3. 访问http://xxxxxx/sys/api
即可查看系统的接口文档。接口文档是JSON格式的，保存到本地，导入到postman即可。

#### 其它说明

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

2. maven依赖用的是springdoc-openapi-core，因为我自己不需要swagger页面，如果需要可替换成springdoc-openapi-ui。



#### 使用样例（与spring-doc一致）

本框架未改动spring-doc的相关功能，spring-doc原始功能依旧可用；
获取spring-doc接口文档：http://xxxx:xxx/项目名/v3/api-docs

```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 ChenSS on 2018/6/20.
 */
@Schema(description = "App信息表 [t_sys_app_info] 实体类")
public class SysAppInfo implements Serializable {
    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;
    /**
     * 文件地址
     */
    @Length(max = 128)
    @Schema(description = "文件地址")
    private String appPath;
    /**
     * 简介
     */
    @Length(max = 255)
    @Schema(description = "简介")
    private String appDesc;
    /**
     * APP产品主页
     */
    @Length(max = 128)
    @Schema(description = "APP产品主页")
    private String appPage;
    /**
     * 更新内容
     */
    @Length(max = 1024)
    @Schema(description = "更新内容")
    private String updateContent;
    /**
     * 文件类型
     */
    @Schema(description = "文件类型")
    private Integer appType;
    /**
     * 创建日期
     */
    @Schema(description = "创建日期")
    private LocalDateTime gmtCreate;
    /**
     * 更新日期
     */
    @Schema(description = "更新日期")
    private LocalDateTime gmtModified;
	
	//下列省略getter/setter
}
```

````java

/**
 * 系统APP文件 [t_sys_app_info] - Controller
 * <p>
 *
 * @author ChenSS 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);
    }
}


````


#### 版本说明

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扫描代码；

#### 参与贡献

1.  Mr.css

#### postman接口规范
https://schema.getpostman.com/json/collection/v2.1.0/docs/index.html