Skip to content
Translate APIs described by OpenAPI Specifications (OAS) into GraphQL
Branch: master
Clone or download
Alan-Cha and ErikWittern Tests in Typescript
Signed-off-by: Alan Cha <Alan.cha1@ibm.com>
Latest commit 0ecb7f7 Jul 11, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/ISSUE_TEMPLATE Update issue templates Oct 12, 2018
docs Changed video ID. Jul 3, 2019
packages Tests in Typescript Jul 17, 2019
.gitignore add tests for PR#97 Jan 29, 2019
.travis.yml Clean up Travis config Jul 3, 2019
CONTRIBUTING.md Rename repository Jun 20, 2019
LICENSE.md Updated license to confirm with MIT template Jun 10, 2019
README.md Remove subOperations and fix link Jul 10, 2019
lerna.json Prettier JSON files Jun 20, 2019
package.json Tests in Typescript Jul 17, 2019

README.md

GitHub last commit Travis (.org) Join the chat at https://gitter.im/IBM/openapi-to-graphql

OpenAPI-to-GraphQL

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

Overview of translation

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.

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.

    Example of data-centric design
  • Nested data Links defined in the OAS are used to create nested data structures, allowing for (deeply) nested queries.

    Example of links resolution
  • Automatic query resolution Automatically generated resolvers translate (nested) GraphQL queries to API requests. Request results are translated back to GraphQL responses.

    Example of query resolution
  • Mutations Non-safe, non-idempotent API operations (e.g., POST, PUT, DELETE) are translated to GraphQL mutations. Input payload is type-checked.

    Example of mutation
  • 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.

    Example of authentication
  • 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.

    Example of sanitation
  • 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 uses the Lerna monorepo management system. After cloning the entire monorepo repository, you can install Lerna with the command npm install and then install the dependencies for all of the packages with lerna bootstrap.

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 npm run build or npm test to transpile the source files into the final library in the lib folder. Entry-point for the library is index.js in lib.

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

You can’t perform that action at this time.