Repository files navigation

Translate APIs described byOpenAPI Specifications (OAS) orSwagger intoGraphQL.

OpenAPI-to-GraphQL can be used in two ways:

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 theopenapi-to-graphql-cli documentation.

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 thecreateGraphQLSchema function:

   const{ createGraphQLSchema}=require("openapi-to-graphql");// load or construct OAS (const oas = ...)const{ schema, report}=awaitcreateGraphQLSchema(oas);

For further details, refer to theopenapi-to-graphql documentation.

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 OASlink 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.

• Data-centricThe GraphQL interface is created around the data definitions in the given OAS, not around the endpoints, leading to a natural use of GraphQL.

  

• Nested dataLinks defined in the OAS are used to create nested data structures, allowing for (deeply) nested queries.

  

• Automatic query resolutionAutomatically generated resolvers translate (nested) GraphQL queries to API requests. Request results are translated back to GraphQL responses.

  

• MutationsNon-safe, non-idempotent API operations (e.g.,POST,PUT,DELETE) are translated to GraphQLmutations. Input payload is type-checked.

  

• SubscriptionsGraphQLsubscriptions 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 oncallback objects defined in the OAS.

  

• AuthenticationOpenAPI-to-GraphQL currently supports authentication via API Key and basic auth. OpenAPI-to-GraphQL wraps secured endpoints into aviewer, which takes the API key / credentials as input.

  

• API SanitationParts 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.

OpenAPI-to-GraphQL is written inTypeScript. Within each of OpenAPI-to-GraphQL's packages, all source code is contained in thesrc folder. Useyarn build oryarn test to transpile the source files into the final library in thedist folder. Entry-point for the library isindex.js indist.

Our research paper, "Generating GraphQL-Wrappers for REST(-like) APIs", can be foundhere. 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 byAPIs.guru, and successfully created GraphQL interfaces for 89.5% of them.

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

npm run guru-load

Then, run tests:

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

• 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.

MIT