Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ibm/openapi-to-graphql
Translate APIs described by OpenAPI Specifications (OAS) into GraphQL
https://github.com/ibm/openapi-to-graphql
graphql oas-to-graphql openapi-specification openapi-to-graphql rest-api swagger swagger-to-graphql translation wrapper
Last synced: about 2 months ago
JSON representation
Translate APIs described by OpenAPI Specifications (OAS) into GraphQL
- Host: GitHub
- URL: https://github.com/ibm/openapi-to-graphql
- Owner: IBM
- License: mit
- Created: 2018-09-05T18:52:16.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2023-12-26T06:13:42.000Z (9 months ago)
- Last Synced: 2024-05-01T12:16:37.806Z (5 months ago)
- Topics: graphql, oas-to-graphql, openapi-specification, openapi-to-graphql, rest-api, swagger, swagger-to-graphql, translation, wrapper
- Language: TypeScript
- Homepage: https://developer.ibm.com/open/projects/openapi-to-graphql/
- Size: 10.3 MB
- Stars: 1,594
- Watchers: 40
- Forks: 206
- Open Issues: 142
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
- awesome-graphql - OpenAPI-to-GraphQL - Take any OpenAPI Specification (OAS) or swagger and create a GraphQL interface - Two minute video and resources [here](https://developer.ibm.com/open/projects/openapi-to-graphql/) (Tools / Julia Libraries)
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).
[](https://gitter.im/IBM/openapi-to-graphql?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
# OpenAPI-to-GraphQL
Translate APIs described by [OpenAPI Specifications (OAS)](https://github.com/OAI/OpenAPI-Specification) or [Swagger](https://swagger.io/specification/v2/) into [GraphQL](https://graphql.org/).
## Getting started
OpenAPI-to-GraphQL can be used in two ways:
### CLI
The Command Line Interface (CLI) provides a convenient way to start a GraphQL server wrapping an API for a given OpenAPI Specification:
1. Install the OpenAPI-to-GraphQL CLI using:
```bash
npm i -g openapi-to-graphql-cli
```
2. Then, run the OpenAPI-to-GraphQL command and point it to an OpenAPI Specification:
```bash
openapi-to-graphql [options]
```
For further details, refer to the [`openapi-to-graphql-cli` documentation](./packages/openapi-to-graphql-cli).
### Library
Use OpenAPI-to-GraphQL as a library in your application to generate GraphQL schemas.
1. Install OpenAPI-to-GraphQL as a dependency:
```bash
npm i -s openapi-to-graphql
```
2. Require OpenAPI-to-GraphQL and use the `createGraphQLSchema` function:
```javascript
const { createGraphQLSchema } = require("openapi-to-graphql");
// load or construct OAS (const oas = ...)
const { schema, report } = await createGraphQLSchema(oas);
```
For further details, refer to the [`openapi-to-graphql` documentation](./packages/openapi-to-graphql).
## Tutorials
Here are some guides to further help you get started:
- [CLI + Loopback tutorial](./docs/tutorials/cli_loopback.md): Learn how to quickly spin up GraphQL wrappers using the OpenAPI-to-GraphQL CLI.
- [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.
- [LoopBack tutorial](./docs/tutorials/loopback.md): Learn how to use OpenAPI-to-GraphQL to create GraphQL wrappers for APIs created with LoopBack 4.
- [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.
## Characteristics
- **Data-centric**
The GraphQL interface is created around the data definitions in the given OAS, not around the endpoints, leading to a natural use of GraphQL.
- **Nested data**
[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.
- **Automatic query resolution**
Automatically generated resolvers translate (nested) GraphQL queries to API requests. Request results are translated back to GraphQL responses.
- **Mutations**
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.
- **Subscriptions**
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.
- **Authentication**
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.
- **API Sanitation**
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.
- **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.
- **Swagger and OpenAPI 3 support** OpenAPI-to-GraphQL can handle both Swagger (OpenAPI specification 2.0) as well as OpenAPI specification 3.
## Development
OpenAPI-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`.
## Research
Our 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.
To 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:
```bash
npm run guru-load
```
Then, run tests:
```bash
npm run guru-test
```
## Similar projects
- [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.
- [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.
- [StackOverflow discussion](https://stackoverflow.com/questions/38339442/json-schema-to-graphql-schema-converters) points to the above projects.
## License
[MIT](./LICENSE.md)