# 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**: 2026-07-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Swagger

## README

## seaboot-openapi

设计背景：想用 OpenAPI 3.0 标准设计我的集成框架，又不希望它影响到我的代码写法。

#### 开发目的

核心目的：重写接口解析代码，用更少的配置，完成接口文档描述。

* 不写 OpenAPI 3.0 的注解，也能导出接口文档，兼容配置缺省的情况；
* 如果采用了 javax.validation/hibernate-validation 注解，则优先使用相关注解的信息；
* 基于这些技术积累，继续给 async-validator 这些相关的库，提供技术支持；

#### OpenAPI 3.0

OpenAPI 3.0（原 Swagger 规范）是当前最流行的 API 描述规范，

用于定义 rest-ful API 的接口文档、数据模型、安全机制等，

支持自动化生成客户端/服务端代码、测试工具和交互式文档。

#### 使用场景

导出 json 或者 yaml 格式的接口文件，导入到 postman 或者其他 UI 插件中使用。

```java
public class Test {

    public static void main(String[] args) {
        // 描述
        Info info = new Info()
                .version("1.0")
                .title("用户管理API")
                .description("用户管理系统的RESTFul API文档")
                .contact(new Contact().name("API支持团队").email("apisupport@example.com"))
                .license(new License().name("Apache 2.0").url("http://www.apache.org/licenses/LICENSE-2.0"));

        Configuration configuration = new Configuration();
        configuration.withResponseParser();

        String api = OpenAPIBuilder.create(configuration)
                .search(AppInfoCtrl.class) // 指定需要扫描的对象或者 spring 容器
                .setInfo(info)
                .addService(new Server().description("生产环境").url("https://api.example.com/v1"))
                .addService(new Server().description("测试环境").url("https://staging-api.example.com/v1"))
                .toJson();

        System.out.println(api);
    }
}

```

#### 兼容

* 接口标准：OpenAPI 3.0；
* 兼容版本：spring-5.3.39；
* 主要针对 rest-ful 中规定的几个函数进行解析；
* 项目依赖仅用到 spring-doc 包下的 swagger-annotations 和 swagger-models；

如果需要内置界面，可以使用 swagger-ui 依赖，因为是基于标准设计的，理论上应当完全兼容，因为我们习惯使用 postman，对界面没有太多研究。

#### 参与贡献

1. Mr.css