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

mkdir petstore-graphql
cd petstore-graphql
npm init

Store the spec as petstore.json

curl -o petstore.json https://petstore.swagger.io/v2/swagger.json

Install SwagQL and other packages to run the server

npm i swagql express express-graphql gofer

Generate a GraphQL schema from the downloaded swagger spec

swagql < petstore.json > petstore-graphql.js

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.

// array-to-connection.js
'use strict';

Create a server using Express

// server.js
'use strict';

Add GraphQL Express to handle the GraphQL requests

// server.js
const graphqlHTTP = require('express-graphql');

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 { schema, FETCH } = require('./petstore-graphql');
const Gofer = require('gofer');

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 Product and Engineering

All things technology from Groupon staff

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

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