{"id":13499610,"url":"https://github.com/ibm/openapi-to-graphql","last_synced_at":"2025-04-11T03:30:08.837Z","repository":{"id":34943558,"uuid":"147564967","full_name":"IBM/openapi-to-graphql","owner":"IBM","description":"Translate APIs described by OpenAPI Specifications (OAS) into GraphQL","archived":false,"fork":false,"pushed_at":"2023-12-26T06:13:42.000Z","size":10826,"stargazers_count":1618,"open_issues_count":140,"forks_count":212,"subscribers_count":38,"default_branch":"master","last_synced_at":"2025-04-10T13:16:14.890Z","etag":null,"topics":["graphql","oas-to-graphql","openapi-specification","openapi-to-graphql","rest-api","swagger","swagger-to-graphql","translation","wrapper"],"latest_commit_sha":null,"homepage":"https://developer.ibm.com/open/projects/openapi-to-graphql/","language":"TypeScript","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/IBM.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-09-05T18:52:16.000Z","updated_at":"2025-03-21T13:44:19.000Z","dependencies_parsed_at":"2024-01-06T03:44:53.250Z","dependency_job_id":"54728e35-6e43-4af0-9d53-f4783d8abef7","html_url":"https://github.com/IBM/openapi-to-graphql","commit_stats":{"total_commits":660,"total_committers":43,"mean_commits":"15.348837209302326","dds":0.5303030303030303,"last_synced_commit":"d6f53e7ee7c0929de4ae67bb868549a236fe4a45"},"previous_names":["strongloop/oasgraph"],"tags_count":104,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM%2Fopenapi-to-graphql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM%2Fopenapi-to-graphql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM%2Fopenapi-to-graphql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM%2Fopenapi-to-graphql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IBM","download_url":"https://codeload.github.com/IBM/openapi-to-graphql/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248335294,"owners_count":21086555,"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":["graphql","oas-to-graphql","openapi-specification","openapi-to-graphql","rest-api","swagger","swagger-to-graphql","translation","wrapper"],"created_at":"2024-07-31T22:00:36.470Z","updated_at":"2025-04-11T03:30:08.794Z","avatar_url":"https://github.com/IBM.png","language":"TypeScript","readme":"# Development on OpenAPI-to-GraphQL has paused. [GraphQL Mesh](https://the-guild.dev/graphql/mesh) is maintaining an [OpenAPI/Swagger handler](https://github.com/ardatan/graphql-mesh/tree/39e8e083cdb5b6e0746a9bdab7cc71555fb40220/packages/loaders/openapi), which is fork of OpenAPI-to-GraphQL. Please find them [here](https://the-guild.dev/graphql/mesh/docs/handlers/openapi).\n\n![GitHub last commit](https://img.shields.io/github/last-commit/ibm/openapi-to-graphql.svg?style=flat)\n[![Join the chat at https://gitter.im/IBM/openapi-to-graphql](https://badges.gitter.im/IBM/openapi-to-graphql.svg?style=flat)](https://gitter.im/IBM/openapi-to-graphql?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\n# OpenAPI-to-GraphQL\n\nTranslate APIs described by [OpenAPI Specifications (OAS)](https://github.com/OAI/OpenAPI-Specification) or [Swagger](https://swagger.io/specification/v2/) into [GraphQL](https://graphql.org/).\n\n\u003cimg src=\"https://raw.githubusercontent.com/ibm/openapi-to-graphql/master/docs/translation.png\" alt=\"Overview of translation\" width=\"600\"\u003e\n\n## Getting started\n\nOpenAPI-to-GraphQL can be used in two ways:\n\n### CLI\n\nThe Command Line Interface (CLI) provides a convenient way to start a GraphQL server wrapping an API for a given OpenAPI Specification:\n\n1. Install the OpenAPI-to-GraphQL CLI using:\n   ```bash\n   npm i -g openapi-to-graphql-cli\n   ```\n2. Then, run the OpenAPI-to-GraphQL command and point it to an OpenAPI Specification:\n   ```bash\n   openapi-to-graphql \u003cOAS JSON file path or remote url\u003e [options]\n   ```\n\nFor further details, refer to the [`openapi-to-graphql-cli` documentation](./packages/openapi-to-graphql-cli).\n\n### Library\n\nUse OpenAPI-to-GraphQL as a library in your application to generate GraphQL schemas.\n\n1. Install OpenAPI-to-GraphQL as a dependency:\n   ```bash\n   npm i -s openapi-to-graphql\n   ```\n2. Require OpenAPI-to-GraphQL and use the `createGraphQLSchema` function:\n   ```javascript\n   const { createGraphQLSchema } = require(\"openapi-to-graphql\");\n   // load or construct OAS (const oas = ...)\n   const { schema, report } = await createGraphQLSchema(oas);\n   ```\n\nFor further details, refer to the [`openapi-to-graphql` documentation](./packages/openapi-to-graphql).\n\n## Tutorials\n\nHere are some guides to further help you get started:\n\n- [CLI + Loopback tutorial](./docs/tutorials/cli_loopback.md): Learn how to quickly spin up GraphQL wrappers using the OpenAPI-to-GraphQL CLI.\n- [Library tutorial](./docs/tutorials/watson.md): Learn how to use OpenAPI-to-GraphQL as a library, and how to improve the resulting GraphQL wrappers using OAS `link` definitions.\n- [LoopBack tutorial](./docs/tutorials/loopback.md): Learn how to use OpenAPI-to-GraphQL to create GraphQL wrappers for APIs created with LoopBack 4.\n- [Subscriptions tutorial](./packages/openapi-to-graphql/docs/subscriptions.md): Learn how to create a GraphQL API that supports subscription operations - including how to set up the API server that creates a PubSub instance wrapping a MQTT client.\n\n## Characteristics\n\n- **Data-centric**\n  The GraphQL interface is created around the data definitions in the given OAS, not around the endpoints, leading to a natural use of GraphQL.\n\n  \u003cimg src=\"https://raw.githubusercontent.com/ibm/openapi-to-graphql/master/docs/data-centric.png\" alt=\"Example of data-centric design\" width=\"600\"\u003e\n\n- **Nested data**\n  [Links](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#linkObject) defined in the OAS are used to create nested data structures, allowing for (deeply) nested queries. \n\n  \u003cimg src=\"https://raw.githubusercontent.com/ibm/openapi-to-graphql/master/docs/links.png\" alt=\"Example of links resolution\" width=\"600\"\u003e\n\n- **Automatic query resolution**\n  Automatically generated resolvers translate (nested) GraphQL queries to API requests. Request results are translated back to GraphQL responses.\n\n  \u003cimg src=\"https://raw.githubusercontent.com/ibm/openapi-to-graphql/master/docs/resolution.png\" alt=\"Example of query resolution\" width=\"600\"\u003e\n\n- **Mutations**\n  Non-safe, non-idempotent API operations (e.g., `POST`, `PUT`, `DELETE`) are translated to GraphQL [mutations](http://graphql.org/learn/queries/#mutations). Input payload is type-checked.\n\n  \u003cimg src=\"https://raw.githubusercontent.com/ibm/openapi-to-graphql/master/docs/mutations.png\" alt=\"Example of mutation\" width=\"600\"\u003e\n  \n- **Subscriptions**\n  GraphQL [subscriptions](http://spec.graphql.org/draft/#sec-Subscription) allow clients to receive a stream of events, such as updates whenever data changes on the GraphQL server. OpenAPI-to-GraphQL can create subscriptions based on [`callback`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#CallbackObject) objects defined in the OAS.\n\n  \u003cimg src=\"https://raw.githubusercontent.com/ibm/openapi-to-graphql/master/docs/subscriptions.png\" alt=\"Example of subscription\" width=\"600\"\u003e\n\n- **Authentication**\n  OpenAPI-to-GraphQL currently supports authentication via API Key and basic auth. OpenAPI-to-GraphQL wraps secured endpoints into a `viewer`, which takes the API key / credentials as input.\n\n  \u003cimg src=\"https://raw.githubusercontent.com/ibm/openapi-to-graphql/master/docs/auth.png\" alt=\"Example of authentication\" width=\"600\"\u003e\n\n- **API Sanitation**\n  Parts of an API that not compatible with GraphQL are automatically sanitized. For example, API parameters and data definition names with unsupported characters (e.g., `-`, `.`, `,`, `:`, `;`...) are removed. GraphQL queries are desanitized to correctly invoke the REST API and the responses are resanitized to create GraphQL-compliant results.\n\n  \u003cimg src=\"https://raw.githubusercontent.com/ibm/openapi-to-graphql/master/docs/sanitization.png\" alt=\"Example of sanitation\" width=\"300\"\u003e\n\n- **Custom request options** Provide headers and query parameters to send with every API request. This allows, for example, to handle authentication or tag requests from GraphQL.\n\n- **Swagger and OpenAPI 3 support** OpenAPI-to-GraphQL can handle both Swagger (OpenAPI specification 2.0) as well as OpenAPI specification 3.\n\n## Development\n\nOpenAPI-to-GraphQL is written in [TypeScript](http://www.typescriptlang.org/). Within each of OpenAPI-to-GraphQL's packages, all source code is contained in the `src` folder. Use `yarn build` or `yarn test` to transpile the source files into the final library in the `dist` folder. Entry-point for the library is `index.js` in `dist`.\n\n## Research\n\nOur research paper, \"Generating GraphQL-Wrappers for REST(-like) APIs\", can be found [here](https://arxiv.org/abs/1809.08319). The paper describes the challenges of building OpenAPI-to-GraphQL and an experiment in which we evaluated OpenAPI-to-GraphQL against 959 publicly available OAS, provided by [APIs.guru](https://apis.guru/), and successfully created GraphQL interfaces for 89.5% of them.\n\nTo run the experiment, in the [`openapi-to-graphql` package](./packages/openapi-to-graphql), load APIs.guru specifications, found [here](https://github.com/APIs-guru/openapi-directory), into the `/tmp` folder:\n\n```bash\nnpm run guru-load\n```\n\nThen, run tests:\n\n```bash\nnpm run guru-test \u003cnumber of APIs to test at most\u003e\n```\n\n## Similar projects\n\n- [swagger-to-graphql](https://github.com/yarax/swagger-to-graphql) turns a given Swagger (OpenAPI Specification 2.0) into a GraphQL interface, which resolves against the original API. GraphQL schema is based on endpoints, not on data definitions. No links are considered.\n\n- [json-to-graphql](https://github.com/aweary/json-to-graphql) turns given JSON objects / arrays into a GraphQL schema. `resolve` functions need to be provided by the user.\n\n- [StackOverflow discussion](https://stackoverflow.com/questions/38339442/json-schema-to-graphql-schema-converters) points to the above projects.\n\n## License\n\n[MIT](./LICENSE.md)\n","funding_links":[],"categories":["Tools"],"sub_categories":["Julia Libraries","Tools - Miscellaneous","Crystal Libraries"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibm%2Fopenapi-to-graphql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fibm%2Fopenapi-to-graphql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibm%2Fopenapi-to-graphql/lists"}