Swagger-to-GraphQL converts your existing Swagger schema to an executable GraphQL schema where resolvers perform HTTP calls to certain real endpoints. It allows you to move your API to GraphQL with nearly zero effort and maintain both REST and GraphQL APIs. Our CLI tool also allows you get the GraphQL schema in Schema Definition Language.
Try it online! You can paste in the url to your own Swagger schema. There are also public OpenAPI schemas available in the APIs.guru OpenAPI directory.
- Swagger (OpenAPI 2) and OpenAPI 3 support
- Bring you own HTTP client
- Typescript types included
- Runs in the browser
- Formdata request body
- Custom request headers
This library will fetch your swagger schema, convert it to a GraphQL schema and convert GraphQL parameters to REST parameters. From there you are control of making the actual REST call. This means you can reuse your existing HTTP client, use existing authentication schemes and override any part of the REST call. You can override the REST host, proxy incoming request headers along to your REST backend, add caching etc.
import express, { Request } from 'express';
import graphqlHTTP from 'express-graphql';
import { createSchema, CallBackendArguments } from 'swagger-to-graphql';
const app = express();
// Define your own http client here
async function callBackend({
context,
requestOptions,
}: CallBackendArguments<Request>) {
return 'Not implemented';
}
createSchema({
swaggerSchema: `./petstore.yaml`,
callBackend,
})
.then(schema => {
app.use(
'/graphql',
graphqlHTTP(() => {
return {
schema,
graphiql: true,
};
}),
);
app.listen(3009, 'localhost', () => {
console.info('http://localhost:3009/graphql');
});
})
.catch(e => {
console.log(e);
});Constructor (graphQLSchema) arguments:
export interface Options<TContext> {
swaggerSchema: string | JSONSchema;
callBackend: (args: CallBackendArguments<TContext>) => Promise<any>;
}swaggerUrl(string) is a path or URL to your swagger schema file. requiredcallBackend(async function) is called with all parameters needed to make a REST call as well as the GraphQL context.
You can use the library just to convert schemas without actually running server
npx swagger-to-graphql --swagger-schema=/path/to/swagger_schema.json > ./types.graphql
Apollo federation support can be added by using graphql-transform-federation. You can extend your swagger-to-graphql schema with other federated schemas or the other way around. See the demo with a transformed schema for a working example.
This repository has:
- node-fetch example. Read more about node-fetch.
- request-promise example. Read more about request.
To get started install node-fetch and copy the
node-fetch example into your server.
npm install node-fetch --saveThere a unit test for our HTTP client example, it might be useful when implementing your own client as well.
The function callBackend is called with 2 parameters:
contextis your GraphQL context. Forexpress-graphqlthis is the incomingrequestobject by default. Read more. Use this if you want to proxy headers likeauthorization. For exampleconst authorizationHeader = context.get('authorization').requestOptionsincludes everything you need to make a REST call.
export interface CallBackendArguments<TContext> {
context: TContext;
requestOptions: RequestOptions;
}export interface RequestOptions {
baseUrl?: string;
path: string;
method: string;
headers?: {
[key: string]: string;
};
query?: {
[key: string]: string | string[];
};
body?: any;
bodyType: 'json' | 'formData';
}baseUrllike defined in your swagger schema:http://my-backend/v2paththe next part of the url:/widgetsmethodHTTP verb:getheadersHTTP headers which are filled using GraphQL parameters:{ api_key: 'xxxx-xxxx' }. Note these are not the http headers sent to the GraphQL server itself. Those will be on thecontextparameterqueryQuery parameters for this calls:{ id: 123 }. Note this can be an array. You can find some examples on how to deal with arrays in query parameters in the qs documentation.bodythe request payload to send with this REST call.bodyTypehow to encode your request payload. When thebodyTypeisformDatathe request should be URL encoded form data. Ensure your HTTP client sends the rightContent-Typeheaders.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent