https://github.com/swaggerql/swaggerql
Easily and simply convert SQL database into a REST API with Swagger documentation
https://github.com/swaggerql/swaggerql
database mariadb mysql oracle postgresql sql sqlite swagger swagger-api swagger-ui
Last synced: 7 months ago
JSON representation
Easily and simply convert SQL database into a REST API with Swagger documentation
- Host: GitHub
- URL: https://github.com/swaggerql/swaggerql
- Owner: swaggerql
- License: mit
- Created: 2019-09-22T13:28:27.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2023-11-20T17:34:24.000Z (almost 2 years ago)
- Last Synced: 2025-03-16T19:37:50.680Z (8 months ago)
- Topics: database, mariadb, mysql, oracle, postgresql, sql, sqlite, swagger, swagger-api, swagger-ui
- Language: JavaScript
- Homepage:
- Size: 786 KB
- Stars: 54
- Watchers: 3
- Forks: 12
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- jimsghstars - swaggerql/swaggerql - Easily and simply convert SQL database into a REST API with Swagger documentation (JavaScript)
README
# SwaggerQL
[](https://github.com/swaggerql/swaggerql/actions/workflows/build.yml)
[](https://github.com/swaggerql/swaggerql/actions/workflows/codeql-analysis.yml)
[](https://hub.docker.com/r/swaggerql/swaggerql-mysql)
[](https://hub.docker.com/r/swaggerql/swaggerql-mariadb)
[](https://hub.docker.com/r/swaggerql/swaggerql-postgres)
[](https://hub.docker.com/r/swaggerql/swaggerql-oracle)
[](https://hub.docker.com/r/swaggerql/swaggerql-sqlite)
**Swagger** + S**QL** = Simple reference microservice with transparent documentation and no coding.
All you need to do is create a Swagger file and specify SQL queries in the description.
When you should use it:
- you need an internal microservice with simple queries to an existing database
- you quickly need a prototype of a reference service
- you need to test data in the database
- you need a stub application with database access to test the deployment scripts
## Getting Started
Install the appropriate database module before using the SwaggerQL:
- `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](https://www.oracle.com/database/technologies/instant-client/linux-x86-64-downloads.html) for Oracle
Run SwaggerQL with PostgreSQL
```sh
npm install swaggerql
npm install pg
```
Create `config/local.yaml`
```yaml
client: pg
connection:
host: 127.0.0.1
user: your_database_user
password: your_database_password
database: myapp_test
```
Run SwaggerQL
```sh
$(npm bin)/swaggerql
```
And try [http://0.0.0.0:8000](http://0.0.0.0:8000)
Run SwaggerQL with Oracle
```sh
npm install swaggerql
npm install oracledb
```
Install [Oracle instant-client](https://www.oracle.com/database/technologies/instant-client/linux-x86-64-downloads.html)
Create `config/local.yaml`
```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
```sh
$(npm bin)/swaggerql
```
And try [http://0.0.0.0:8000](http://0.0.0.0:8000)
More examples in [the repository](https://github.com/swaggerql/swaggerql/tree/master/examples).
## Configuration
### Connect to DB
The [knex](https://github.com/tgriesser/knex) library is used to connect to various databases.
The most common configuration file format is:
```yaml
client:
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](http://knexjs.org/#Installation-client)
See [node-config](https://github.com/lorenwest/node-config/wiki/Configuration-Files) documentation for information about naming,
load order and format of configuration files.
### REST API
Build APIs by describing them in [OpenAPI document specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md)
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.
```yaml
paths:
/two:
get:
summary: One plus one equals two
description: |
SELECT 1 + 1
responses:
200:
description: OK
```
The description can use Markdown with a specified SQL query:
````yaml
description: |
Add one to one
```sql
SELECT 1 + 1
```
````
#### Query Parameter Binding
You can pass parameters to SQL query from `path`, `query`, `form` parameters described in Swagger file.
Use named bindings, such as `:name` are interpreted as values and `:name:` interpreted as identifiers.
```yaml
paths:
/increment:
get:
summary: Increment of N per one
description: |
SELECT 1 + :n
parameters:
- name: n
in: query
description: Number
required: true
style: form
explode: true
schema:
type: integer
responses:
200:
description: OK
```
#### Execution options
Query expression can be handled as a transaction if the client sends `X-Transaction` header.
Sometimes there's need to release cursors in the database.
```yaml
paths:
/compute:
get:
summary: Adding the results of a calculation
description: |
insert into table
select function()
parameters:
- name: X-Transaction
in: header
description: Run Query in transaction wrapper
schema:
type: boolean
default: true
```
## CLI
Configuration options can be overridden via command-line arguments or environment variables.
Priorities are the following:
- A command-line option has the highest priority. It overrides the environment variable and config file value.
- An environment variable has second priority. It overrides the config file value.
- A config file value has the lowest priority.
- If there isn't a command-line option, environment variable or config file option specified, the default is used.
Run `$(npm bin)/swaggerql --help` for more information.
```
Usage: swaggerql [options]
Options:
-V, --version output the version number
-i, --input-spec path to specification file (default: "openapi.yaml")
-p, --port http port to start server (default: 8000)
-d, --client name of client SQL driver
-c, --connection connection options to the appropriate database client
-l, --log-level logging level: debug, info, warn, error (default: "info")
-h, --help output usage information
```
Environment variables:
- `SWAGGERQL_INPUT_SPEC` — path to specification file
- `SWAGGERQL_PORT` — http port to start server
- `SWAGGERQL_CLIENT` — name of client SQL driver
- `SWAGGERQL_CONNECTION` — connection options to the appropriate database client
- `SWAGGERQL_LOG_LEVEL` — logging level
## Docker
```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-mysql
```
Available Docker containers:
- [swaggerql/swaggerql-mysql](https://hub.docker.com/r/swaggerql/swaggerql-mysql)
- [swaggerql/swaggerql-mariadb](https://hub.docker.com/r/swaggerql/swaggerql-mariadb)
- [swaggerql/swaggerql-postgres](https://hub.docker.com/r/swaggerql/swaggerql-postgres)
- [swaggerql/swaggerql-oracle](https://hub.docker.com/r/swaggerql/swaggerql-oracle)
- [swaggerql/swaggerql-sqlite](https://hub.docker.com/r/swaggerql/swaggerql-sqlite)