Translate APIs described by OpenAPI Specifications (OAS) into GraphQL.
OASGraph 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:
- Install the OASGraph CLI using:
npm i -g oasgraph-cli
- Then, run the OASGraph command and point it to an OpenAPI Specification:
oasgraph <OAS JSON file path or remote url> [options]
For further details, refer to the oasgraph-cli
documentation.
Use OASGraph as a library in your application to generate GraphQL schemas.
- Install OASGraph as a dependency:
npm i -s oasgraph
- Require OASGraph and use the
createGraphQlSchema
function:const { createGraphQlSchema } = require('oasgraph') // load or construct OAS (const oas = ...) const { schema, report } = await createGraphQlSchema(oas)
For further details, refer to the oasgraph
documentation.
Here are some guides to further help you get started:
- CLI + Loopback tutorial: Learn how to quickly spin up GraphQL wrappers using the OASGraph CLI.
- Library tutorial: Learn how to use OASGraph as a library, and how to improve the resulting GraphQL wrappers using OAS
link
definitions. - LoopBack tutorial: Learn how to use OASGraph to create GraphQL wrappers for APIs created with LoopBack 4.
-
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 compose data definitions. Furthermore, hierarchical path structures can be used to nest data via the
addSubOperations
option. -
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. -
Authentication OASGraph currently supports authentication via API Key and basic auth. OASGraph 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 OASGraph can handle both Swagger (OpenAPI specification 2.0) as well as OpenAPI specification 3.
OASGraph 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
.
OASGraph is written in TypeScript. Within each of OASGraph'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
.
Our research paper, "Generating GraphQL-Wrappers for REST(-like) APIs", can be found here. The paper describes the challenges of building OASGraph and an experiment in which we evaluated OASGraph 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 oasgraph
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>
-
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.