swaggerql/swaggerql-oracle

SwaggerQL Docker镜像文档

镜像概述与主要用途

SwaggerQL是Swagger与SQL的结合，提供无需编码即可创建具有透明文档的参考微服务。只需创建Swagger文件并在描述中指定SQL查询，即可快速构建数据库访问服务。本镜像专为Oracle数据库设计，适用于快速开发、测试和部署数据库查询服务。

核心功能与特性

• 零编码开发：通过Swagger文件定义API，在描述字段中嵌入SQL查询即可创建服务
• Oracle数据库支持：集成Oracle数据库驱动和即时客户端，实现高效连接
• 透明文档：自动生成Swagger UI文档，API与文档保持同步
• 参数绑定：支持从路径、查询、表单参数向SQL查询传递参数
• 事务支持：通过X-Transaction头控制查询事务执行
• 灵活配置：支持配置文件、环境变量和命令行参数多种配置方式

使用场景

• 需要快速构建访问现有Oracle数据库的内部微服务
• 快速原型化数据库查询参考服务
• 测试Oracle数据库中的数据
• 作为带有数据库访问功能的存根应用，测试部署脚本

使用方法与配置说明

前提条件

使用Oracle版本镜像需准备：

• Oracle数据库连接信息
• 符合OpenAPI规范的Swagger文件（openapi.yaml/json）
• 配置文件（指定数据库连接参数）

Docker运行示例

bash
docker run -it --rm -p 8000:8000 \
        -v $(pwd)/config/local.yaml:/app/config/production.yaml \
        -v $(pwd)/openapi.yaml:/app/openapi.yaml \
        swaggerql/swaggerql-oracle

访问 [***] 即可使用Swagger UI界面。

配置文件说明

配置文件采用YAML格式，使用knex库进行数据库连接，典型Oracle配置示例：

yaml
client: oracledb
connection:
  user: your_database_user
  password: your_database_password
  connectString: (DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=127.0.0.1)(PORT=1521)))(CONNECT_DATA=(SID=MY_SID)))
pool:
  min: 0
  max: 3

REST API定义

在Swagger文件的description字段中嵌入SQL查询定义API：

基础查询示例

yaml
paths:
  /two:
    get:
      summary: 一加一等于二
      description: |
        SELECT 1 + 1
      responses:
        200:
          description: 成功响应

Markdown格式SQL

yaml
description: |
  计算一加一的结果
  
  ```sql
  SELECT 1 + 1

#### 参数绑定

支持从请求参数向SQL传递值，使用`:参数名`作为值绑定，`:参数名:`作为标识符绑定：

```yaml
paths:
  /increment:
    get:
      summary: 数字加一
      description: |
        SELECT 1 + :n
      parameters:
      - name: n
        in: query
        description: 待加数字
        required: true
        schema:
          type: integer
      responses:
        200:
          description: 计算结果

事务控制

通过X-Transaction请求头控制查询是否在事务中执行：

yaml
paths:
  /compute:
    get:
      summary: 执行计算并插入结果
      description: |
        INSERT INTO results SELECT function()
      parameters:
      - name: X-Transaction
        in: header
        description: 是否在事务中执行
        schema:
          type: boolean
          default: true

CLI选项与环境变量

可通过命令行参数或环境变量覆盖配置：

命令行选项

Usage: swaggerql [options]

Options:
  -V, --version                输出版本号
  -i, --input-spec <path>      规范文件路径 (默认: "openapi.yaml")
  -p, --port <number>          服务器端口 (默认: 8000)
  -d, --client <name>          SQL驱动名称
  -c, --connection <dsn|json>  数据库连接选项
  -l, --log-level <level>      日志级别: debug, info, warn, error (默认: "info")
  -h, --help                   显示帮助信息

环境变量

• SWAGGERQL_INPUT_SPEC - 规范文件路径
• SWAGGERQL_PORT - 服务器端口
• SWAGGERQL_CLIENT - SQL驱动名称
• SWAGGERQL_CONNECTION - 数据库连接选项
• SWAGGERQL_LOG_LEVEL - 日志级别

可用Docker镜像

SwaggerQL提供多种数据库版本的Docker镜像：

• https://hub.docker.com/r/swaggerql/swaggerql-mysql - MySQL版本
• https://hub.docker.com/r/swaggerql/swaggerql-mariadb - MariaDB版本
• https://hub.docker.com/r/swaggerql/swaggerql-postgres - PostgreSQL版本
• https://hub.docker.com/r/swaggerql/swaggerql-oracle - Oracle版本
• https://hub.docker.com/r/swaggerql/swaggerql-sqlite - SQLite版本