SwagQL

Use GraphQL in minutes, leave the REST to us

Saumitra Bhanage
Mar 4, 2019 · 3 min read
Image for post
Image for post
Build GraphQL schema from a given Swagger schema

GraphQL provides a structured approach to fetch and update data. It has several advantages over REST, such as client-driven development, where the client can request any data they need and GraphQL server will determine where to get that data from. It also prevents over-fetching and under-fetching by providing the precise amount of data the client needs.

If you are creating a new API backend, considering GraphQL for all API interaction is practical. But what if you have a REST-based API already available in production? It helps to start developing new client features using a GraphQL interface which relies on your own battle-tested REST APIs. To do that, we have built SwagQL.

SwagQL takes the Swagger (a.k.a. OpenAPI) specification generated/used by a given REST API backend and builds a GraphQL schema in minutes.

The generated schema includes Type definitions, Queries, and Mutations which map to the endpoints represented in the Swagger schema. It also handles the connections between different objects and pagination. If you want to inject authentication checks early in the data fetch cycle, SwagQL provides you a pluggable function for that.


Let’s jump into creating a simple GraphQL server using SwagQL!

Take an example Swagger spec such as the Petstore example at https://petstore.swagger.io/. We will build a GraphQL interface for this backend using a few steps.

Image for post
Image for post

Create an npm package

Store the spec as petstore.json

Install SwagQL and other packages to run the server

Generate a GraphQL schema from the downloaded swagger spec

Add pagination support by creating a file named array-to-connection.js. For now, we will refer to the default implementation of array-to-connection in SwagQL.

module.exports = require('swagql/array-to-connection.js');

Create a server using Express

const PORT = 8000;
const express = require('express');
const app = express();
app.listen(PORT);
console.log(`Listening on http://localhost:${PORT}`);

Add GraphQL Express to handle the GraphQL requests

// before app.listen
app.use('/graphql', graphqlHTTP({
graphiql: true
}));

Add Schema and Context for GraphQL handler. The generated schema exposes a symbol named FETCH which allows us to specify the fetch function of your API client. An API client has the details such as the base url, proxy setup, etc. To provide the fetch function to the schema, we set it as FETCH property of the context. For this example, let’s create an apiClient using the Gofer library.

const apiClient = new Gofer()
.with({baseUrl: 'http://petstore.swagger.io/v2'});
app.use('/graphql', graphqlHTTP({
schema: schema,
context: { [FETCH]: apiClient.fetch.bind(apiClient) },
graphiql: true
}));

That’s it! Here is the entire server.js

Go ahead and visit http://localhost:8000/graphql to open the GraphiQL interface and try a simple query.

Image for post
Image for post

Feel free to try out SwagQL for your Swagger/OpenAPI Schema. Please note that you may have to customize array-to-connection if your REST APIs handle pagination differently than the default implementation.

In certain cases, you may want to check the authentication and authorization of a request before hitting the backend. To facilitate that, SwagQL exposes a Symbol named VERIFY_AUTH_STATUS. You can define a function that checks auth status for a given request and pass it to the schema as context[VERIFY_AUTH_STATUS]. Please find more details in the SwagQL README.

Please report issues at https://github.com/groupon/swagql/issues

Groupon Engineering

Tech blog from Groupon Engineers

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store