IBM/openapi-to-graphql

Development on OpenAPI-to-GraphQL has paused. GraphQL Mesh is maintaining an OpenAPI/Swagger handler, which is a fork of OpenAPI-to-GraphQL. Please find them here.

OpenAPI-to-GraphQL

Translate APIs described by OpenAPI Specifications (OAS) or Swagger into GraphQL.

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:

   npm i -g openapi-to-graphql-cli
   

2. Then, run the OpenAPI-to-GraphQL command and point it to an OpenAPI Specification:

   openapi-to-graphql <OAS JSON file path or remote url> [options]
   

For further details, refer to the openapi-to-graphql-cli documentation.

Library

Use OpenAPI-to-GraphQL as a library in your application to generate GraphQL schemas.

1. Install OpenAPI-to-GraphQL as a dependency:

   npm i -s openapi-to-graphql
   

2. Require OpenAPI-to-GraphQL and use the createGraphQLSchema function:

   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.

Tutorials

Here are some guides to further help you get started:

• CLI + Loopback tutorial: Learn how to quickly spin up GraphQL wrappers using the OpenAPI-to-GraphQL CLI.
• Library tutorial: Learn how to use OpenAPI-to-GraphQL as a library, and how to improve the resulting GraphQL wrappers using OAS link definitions.
• LoopBack tutorial: Learn how to use OpenAPI-to-GraphQL to create GraphQL wrappers for APIs created with LoopBack 4.
• Subscriptions tutorial: 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 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. Input payload is type-checked.

  

• Subscriptions GraphQL subscriptions 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 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. 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. 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, and successfully created GraphQL interfaces for 89.5% of them.

To run the experiment, in the openapi-to-graphql package, load APIs.guru specifications, found here, into the /tmp folder:

npm run guru-load

Then, run tests:

npm run guru-test <number of APIs to test at most>

Similar projects

• 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 turns given JSON objects / arrays into a GraphQL schema. resolve functions need to be provided by the user.

• StackOverflow discussion points to the above projects.

License

MIT