SwaggerQL

Swagger + SQL = Simple reference microservice with transparent documentation and no coding.

Getting Started

You will need to install the SwaggerQL, and then install the appropriate database module:

• pg for PostgreSQL and Amazon Redshift
• mysql2 for MySQL
• mysql for MariaDB or MySQL
• sqlite3 for SQLite3
• mssql for MSSQL
• oracledb and Oracle instant-client for Oracle

Run SwaggerQL with PostgreSQL

npm install swaggerql
npm install pg

Create config/local.yaml

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

Run SwaggerQL

$(npm bin)/swaggerql

And try http://0.0.0.0:8000

Run SwaggerQL with Oracle

npm install swaggerql
npm install oracledb

Install Oracle instant-client

Create config/local.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

Run SwaggerQL

$(npm bin)/swaggerql

And try http://0.0.0.0:8000

Configuration

Connect to DB

See node-config documentation for information about naming, load order and format of configuration files.

The knex library is used to connect to various databases. The most common configuration file format is:

client: <driver>
connection:
  host: 127.0.0.1
  user: your_database_user
  password: your_database_password
  database: myapp_test

More examples of connection configurations in Knex documentation

REST API

Build APIs by describing them in OpenAPI document specification and importing them via YAML or JSON to construct your own REST API.

The only difference is that a SQL query is inserted into the description field.

paths:
  /two:
    get:
      summary: One plus one equals two
      description: |
        SELECT 1+1
      responses:
        200:
          description: OK

CLI

Run $(npm bin)/swaggerql --help for more information.

Usage: swaggerql [options]

Options:
  -V, --version                output the version number
  -i, --input-spec <path>      path to specification file (default: "openapi.yaml")
  -p, --port <number>          http port to start server (default: 8000)
  -d, --client <name>          name of client SQL driver
  -c, --connection <dsn|json>  connection options to the appropriate database client
  -h, --help                   output usage information

Docker

# Build
docker build --build-arg BASE_CONTAINER=levonet/instantclient-node:18.3-10-slim --build-arg DRIVER_MODULE=oracledb -t swaggerql-oracledb:latest .

# Run
docker run -it --rm -p 8000:8000 -v $(pwd)/config/local.yaml:/app/config/production.yaml swaggerql-oracledb:latest