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 dataLinks 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.
请发表评论