{"id":13941524,"url":"https://github.com/swaggerql/swaggerql","last_synced_at":"2025-04-06T01:32:41.325Z","repository":{"id":35146113,"uuid":"210151975","full_name":"swaggerql/swaggerql","owner":"swaggerql","description":"Easily and simply convert SQL database into a REST API with Swagger documentation","archived":false,"fork":false,"pushed_at":"2023-11-20T17:34:24.000Z","size":805,"stargazers_count":54,"open_issues_count":5,"forks_count":12,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-16T19:37:50.680Z","etag":null,"topics":["database","mariadb","mysql","oracle","postgresql","sql","sqlite","swagger","swagger-api","swagger-ui"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/swaggerql.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2019-09-22T13:28:27.000Z","updated_at":"2025-02-01T14:37:52.000Z","dependencies_parsed_at":"2023-11-20T18:49:00.952Z","dependency_job_id":null,"html_url":"https://github.com/swaggerql/swaggerql","commit_stats":{"total_commits":49,"total_committers":2,"mean_commits":24.5,"dds":"0.26530612244897955","last_synced_commit":"6bf2336d989873cbfbefe3aef15e61aad94b816a"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swaggerql%2Fswaggerql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swaggerql%2Fswaggerql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swaggerql%2Fswaggerql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swaggerql%2Fswaggerql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/swaggerql","download_url":"https://codeload.github.com/swaggerql/swaggerql/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247423472,"owners_count":20936621,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","mariadb","mysql","oracle","postgresql","sql","sqlite","swagger","swagger-api","swagger-ui"],"created_at":"2024-08-08T02:01:20.581Z","updated_at":"2025-04-06T01:32:36.296Z","avatar_url":"https://github.com/swaggerql.png","language":"JavaScript","readme":"# SwaggerQL\n[![Build Status](https://github.com/swaggerql/swaggerql/actions/workflows/build.yml/badge.svg)](https://github.com/swaggerql/swaggerql/actions/workflows/build.yml)\n[![CodeQL](https://github.com/swaggerql/swaggerql/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/swaggerql/swaggerql/actions/workflows/codeql-analysis.yml)\n[![Docker swaggerql-mysql](https://img.shields.io/badge/docker-swaggerql--mysql-green)](https://hub.docker.com/r/swaggerql/swaggerql-mysql)\n[![Docker swaggerql-mariadb](https://img.shields.io/badge/docker-swaggerql--mariadb-green)](https://hub.docker.com/r/swaggerql/swaggerql-mariadb)\n[![Docker swaggerql-postgres](https://img.shields.io/badge/docker-swaggerql--postgres-green)](https://hub.docker.com/r/swaggerql/swaggerql-postgres)\n[![Docker swaggerql-oracle](https://img.shields.io/badge/docker-swaggerql--oracle-green)](https://hub.docker.com/r/swaggerql/swaggerql-oracle)\n[![Docker swaggerql-sqlite](https://img.shields.io/badge/docker-swaggerql--sqlite-green)](https://hub.docker.com/r/swaggerql/swaggerql-sqlite)\n\n**Swagger** + S**QL** = Simple reference microservice with transparent documentation and no coding.  \nAll you need to do is create a Swagger file and specify SQL queries in the description.\n\nWhen you should use it:\n- you need an internal microservice with simple queries to an existing database\n- you quickly need a prototype of a reference service\n- you need to test data in the database\n- you need a stub application with database access to test the deployment scripts\n\n![Screenshot](https://raw.githubusercontent.com/swaggerql/swaggerql/master/screenshot.png)\n\n## Getting Started\n\nInstall the appropriate database module before using the SwaggerQL:\n- `pg` for PostgreSQL and Amazon Redshift\n- `mysql2` for MySQL\n- `mysql` for MariaDB or MySQL\n- `sqlite3` for SQLite3\n- `mssql` for MSSQL\n- `oracledb` and [Oracle instant-client](https://www.oracle.com/database/technologies/instant-client/linux-x86-64-downloads.html) for Oracle\n\n\u003cdetails open\u003e\n\u003csummary\u003e\u003cstrong\u003eRun SwaggerQL with PostgreSQL\u003c/strong\u003e\u003c/summary\u003e\n\n```sh\nnpm install swaggerql\nnpm install pg\n```\n\nCreate `config/local.yaml`\n\n```yaml\nclient: pg\nconnection:\n  host: 127.0.0.1\n  user: your_database_user\n  password: your_database_password\n  database: myapp_test\n```\n\nRun SwaggerQL\n\n```sh\n$(npm bin)/swaggerql\n```\n\nAnd try [http://0.0.0.0:8000](http://0.0.0.0:8000)\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eRun SwaggerQL with Oracle\u003c/strong\u003e\u003c/summary\u003e\n\n```sh\nnpm install swaggerql\nnpm install oracledb\n```\nInstall [Oracle instant-client](https://www.oracle.com/database/technologies/instant-client/linux-x86-64-downloads.html)\n\nCreate `config/local.yaml`\n\n```yaml\nclient: oracledb\nconnection:\n  user: your_database_user\n  password: your_database_password\n  connectString: (DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=127.0.0.1)(PORT=1521)))(CONNECT_DATA=(SID=MY_SID)))\npool:\n  min: 0\n  max: 3\n```\n\nRun SwaggerQL\n\n```sh\n$(npm bin)/swaggerql\n```\n\nAnd try [http://0.0.0.0:8000](http://0.0.0.0:8000)\n\u003c/details\u003e\n\nMore examples in [the repository](https://github.com/swaggerql/swaggerql/tree/master/examples).\n\n## Configuration\n\n### Connect to DB\n\nThe [knex](https://github.com/tgriesser/knex) library is used to connect to various databases.\nThe most common configuration file format is:\n\n```yaml\nclient: \u003cdriver\u003e\nconnection:\n  host: 127.0.0.1\n  user: your_database_user\n  password: your_database_password\n  database: myapp_test\n```\n\nMore examples of connection configurations in [Knex documentation](http://knexjs.org/#Installation-client)\n\nSee [node-config](https://github.com/lorenwest/node-config/wiki/Configuration-Files) documentation for information about naming,\nload order and format of configuration files.\n\n### REST API\n\nBuild APIs by describing them in [OpenAPI document specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md)\nand importing them via YAML or JSON to construct your own REST API.\n\nThe only difference is that a SQL query is inserted into the description field.\n\n```yaml\npaths:\n  /two:\n    get:\n      summary: One plus one equals two\n      description: |\n        SELECT 1 + 1\n      responses:\n        200:\n          description: OK\n```\n\nThe description can use Markdown with a specified SQL query:\n\n````yaml\ndescription: |\n  Add one to one\n\n  ```sql\n  SELECT 1 + 1\n  ```\n````\n\n#### Query Parameter Binding\n\nYou can pass parameters to SQL query from `path`, `query`, `form` parameters described in Swagger file.\nUse named bindings, such as `:name` are interpreted as values and `:name:` interpreted as identifiers.\n\n```yaml\npaths:\n  /increment:\n    get:\n      summary: Increment of N per one\n      description: |\n        SELECT 1 + :n\n      parameters:\n      - name: n\n        in: query\n        description: Number\n        required: true\n        style: form\n        explode: true\n        schema:\n          type: integer\n      responses:\n        200:\n          description: OK\n```\n\n#### Execution options\n\nQuery expression can be handled as a transaction if the client sends `X-Transaction` header.\nSometimes there's need to release cursors in the database.\n\n```yaml\npaths:\n  /compute:\n    get:\n      summary: Adding the results of a calculation\n      description: |\n        insert into table\n        select function()\n      parameters:\n      - name: X-Transaction\n        in: header\n        description: Run Query in transaction wrapper\n        schema:\n          type: boolean\n          default: true\n```\n\n## CLI\n\nConfiguration options can be overridden via command-line arguments or environment variables.\nPriorities are the following:\n- A command-line option has the highest priority. It overrides the environment variable and config file value.\n- An environment variable has second priority. It overrides the config file value.\n- A config file value has the lowest priority.\n- If there isn't a command-line option, environment variable or config file option specified, the default is used.\n\nRun `$(npm bin)/swaggerql --help` for more information.\n\n```\nUsage: swaggerql [options]\n\nOptions:\n  -V, --version                output the version number\n  -i, --input-spec \u003cpath\u003e      path to specification file (default: \"openapi.yaml\")\n  -p, --port \u003cnumber\u003e          http port to start server (default: 8000)\n  -d, --client \u003cname\u003e          name of client SQL driver\n  -c, --connection \u003cdsn|json\u003e  connection options to the appropriate database client\n  -l, --log-level \u003clevel\u003e      logging level: debug, info, warn, error (default: \"info\")\n  -h, --help                   output usage information\n```\n\nEnvironment variables:\n- `SWAGGERQL_INPUT_SPEC` — path to specification file\n- `SWAGGERQL_PORT` — http port to start server\n- `SWAGGERQL_CLIENT` — name of client SQL driver\n- `SWAGGERQL_CONNECTION` — connection options to the appropriate database client\n- `SWAGGERQL_LOG_LEVEL` — logging level\n\n## Docker\n\n```sh\ndocker run -it --rm -p 8000:8000 \\\n        -v $(pwd)/config/local.yaml:/app/config/production.yaml \\\n        -v $(pwd)/openapi.yaml:/app/openapi.yaml \\\n        swaggerql/swaggerql-mysql\n```\n\nAvailable Docker containers:\n- [swaggerql/swaggerql-mysql](https://hub.docker.com/r/swaggerql/swaggerql-mysql)\n- [swaggerql/swaggerql-mariadb](https://hub.docker.com/r/swaggerql/swaggerql-mariadb)\n- [swaggerql/swaggerql-postgres](https://hub.docker.com/r/swaggerql/swaggerql-postgres)\n- [swaggerql/swaggerql-oracle](https://hub.docker.com/r/swaggerql/swaggerql-oracle)\n- [swaggerql/swaggerql-sqlite](https://hub.docker.com/r/swaggerql/swaggerql-sqlite)\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswaggerql%2Fswaggerql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fswaggerql%2Fswaggerql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswaggerql%2Fswaggerql/lists"}