Swagger-to-GraphQL

Swagger-to-GraphQL converts your existing Swagger schema to an executableGraphQL schema where resolvers perform HTTP calls to certain real endpoints. Itallows you to move your API to GraphQL with nearly zero effort and maintain bothREST and GraphQL APIs. Our CLI tool also allows you get the GraphQL schema inSchema Definition Language.

Try it online! You can paste inthe url to your own Swagger schema. There are also public OpenAPI schemasavailable in the APIs.guru OpenAPI directory.

Features

• 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

Usage

Basic server

This library will fetch your swagger schema, convert it to a GraphQL schema andconvert GraphQL parameters to REST parameters. From there you are control ofmaking 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. Youcan override the REST host, proxy incoming request headers along to your RESTbackend, 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. required
• callBackend (async function) is called with all parameters needed to make aREST call as well as the GraphQL context.

CLI usage

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

Apollo federation support can be added by usinggraphql-transform-federation.You can extend your swagger-to-graphql schema with other federated schemas orthe other way around. See thedemo with a transformed schemafor a working example.

Defining your HTTP client

This repository has:

• node-fetch example. Read more aboutnode-fetch.
• request-promise example. Read more aboutrequest.

To get started install node-fetch and copy thenode-fetch example into your server.

npm install node-fetch --save

Implementing your own HTTP client

There 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:

• context is your GraphQL context. For express-graphql this is the incomingrequest object by default.Read more. Use this ifyou want to proxy headers like authorization. For exampleconst authorizationHeader = context.get('authorization').
• requestOptions includes everything you need to make a REST call.

export interface CallBackendArguments<TContext> {
  context: TContext;
  requestOptions: 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';
}

• baseUrl like defined in your swagger schema: http://my-backend/v2
• path the next part of the url: /widgets
• method HTTP verb: get
• headers HTTP headers which are filled using GraphQL parameters:{ api_key: 'xxxx-xxxx' }. Note these are not the http headers sent to theGraphQL server itself. Those will be on the context parameter
• query Query parameters for this calls: { id: 123 }. Note this can be anarray. You can find some examples on how to deal with arrays in queryparameters in theqs documentation.
• body the request payload to send with this REST call.
• bodyType how to encode your request payload. When the bodyType isformData the request should be URL encoded form data. Ensure your HTTPclient sends the right Content-Type headers.

Resources

• Blogpost v3:Start with GraphQL today by converting your Swagger schema
• Blogpost:Moving existing API from REST to GraphQL
• Video:O.J. Sousa Rodrigues at Vienna.JS