swaggerql/swaggerql-postgres

SwaggerQL

![Build Status]([***]

Swagger + SQL = 无需编码即可构建带透明文档的参考微服务。只需创建Swagger文件并在描述中指定SQL查询即可使用。

镜像概述

SwaggerQL是一款将Swagger文档与SQL查询结合的工具，旨在快速构建轻量级RESTful Web服务。该镜像针对PostgreSQL数据库优化，支持通过配置文件连接数据库，并通过Swagger文档定义API接口与嵌入SQL逻辑，适用于快速原型开发、内部微服务搭建等场景。

核心功能

1. 无代码API构建：通过Swagger文件定义接口，在描述中嵌入SQL查询即可生成API
2. 多数据库支持：兼容PostgreSQL、MySQL、MariaDB、SQLite等多种数据库（需对应镜像）
3. 参数绑定：支持从路径、查询、表单参数传递值到SQL查询
4. 事务支持：通过X-Transaction header实现事务包裹查询
5. 灵活配置：通过配置文件、CLI参数或环境变量自定义服务端口、数据库连接等

使用场景

• 需要为现有数据库快速搭建内部简单查询微服务
• 快速生成参考服务原型验证业务逻辑
• 测试数据库中的数据内容
• 构建用于测试部署脚本的数据库访问存根应用

配置说明

连接数据库

使用https://github.com/tgriesser/knex%E5%BA%93%E8%BF%9E%E6%8E%A5%E6%95%B0%E6%8D%AE%E5%BA%93%EF%BC%8C%E9%85%8D%E7%BD%AE%E6%96%87%E4%BB%B6%E6%A0%BC%E5%BC%8F%E7%A4%BA%E4%BE%8B%EF%BC%88PostgreSQL%EF%BC%89%EF%BC%9A

yaml
client: pg
connection:
  host: 127.0.0.1
  user: your_database_user
  password: your_database_password
  database: myapp_test

更多连接配置参考knex文档。

REST API定义

通过OpenAPI文档定义接口，在description字段嵌入SQL查询：

yaml
paths:
  /increment:
    get:
      summary: 数字N加1
      description: |
        SELECT 1 + :n
      parameters:
      - name: n
        in: query
        required: true
        schema:
          type: integer
      responses:
        200:
          description: OK

支持Markdown格式包裹SQL代码块，以及参数绑定（:name为值绑定，:name:为标识符绑定）。

CLI参数

可通过命令行参数覆盖配置：

sh
$(npm bin)/swaggerql --help
# 选项包括：--input-spec（Swagger文件路径）、--port（服务端口）、--client（数据库驱动）等

环境变量支持：SWAGGERQL_INPUT_SPEC、SWAGGERQL_PORT、SWAGGERQL_CLIENT等。

Docker部署示例

PostgreSQL镜像运行

sh
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-postgres

访问http://0.0.0.0:8000即可查看API文档与测试接口。

其他数据库镜像

可替换镜像名称使用对应数据库版本：swaggerql-mysql、swaggerql-mariadb、swaggerql-oracle、swaggerql-sqlite。