https://github.com/groupon/swagql

Create a GraphQL schema from swagger spec
https://github.com/groupon/swagql

graphql javascript nodejs openapi swagger

Last synced: 4 months ago
JSON representation

Create a GraphQL schema from swagger spec

• Host: GitHub
• URL: https://github.com/groupon/swagql
• Owner: groupon
• License: bsd-3-clause
• Created: 2019-02-12T18:05:22.000Z (almost 6 years ago)
• Default Branch: main
• Last Pushed: 2023-01-07T04:01:56.000Z (almost 2 years ago)
• Last Synced: 2024-08-07T19:52:58.185Z (4 months ago)
• Topics: graphql, javascript, nodejs, openapi, swagger
• Language: JavaScript
• Size: 700 KB
• Stars: 46
• Watchers: 11
• Forks: 4
• Open Issues: 9
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE

Awesome Lists containing this project

README

        
[![nlm-github](https://img.shields.io/badge/github-groupon%2Fswagql%2Fissues-F4D03F?logo=github&logoColor=white)](https://github.com/groupon/swagql/issues)

![nlm-node](https://img.shields.io/badge/node-%3E%3D10.13-blue?logo=node.js&logoColor=white)

![nlm-version](https://img.shields.io/badge/version-1.4.0-blue?logo=version&logoColor=white)







Build a GraphQL schema from a given Swagger or Open API specification.

## Install

To install swagql as devDependency run:

```bash

npm i -D swagql

```

## Usage

```bash

cat swagger.yml | npx swagql [-p ,] [-n NamePrefix_]> schema.js

```

Input swagger schema can be in YAML or JSON format. The generated schema exports

a `schema` object and two symbols `FETCH` and `VERIFY_AUTH_STATUS`. These

symbols should reside in the `context` used while creating the GraphQL server.

The definition of `VERIFY_AUTH_STATUS` symbol is optional. It is used to check

the authorization status for given request and swagger auth config. If a given

request does not satisfy the required auth status, you can throw an auth error

from this function. `requestContext` can be used to hold the information about

the current request, such as the request object itself.

In the case where you are merging multiple schemas, you may wish to have all

of the methods and types be unique, and can pass the `--name-prefix` (or `-n`)

flag to prepend the given string to all of the above.

```js

const { schema, FETCH, VERIFY_AUTH_STATUS } = require(pathToSchema);

function verifyAuthStatus(requestContext, authConfig) {

    // verify if current request satisfies authConfig for the given endpoint.

    // if not, throw an auth error.

}

const context = {

  [FETCH]: apiClient.fetch,

  [VERIFY_AUTH_STATUS]: verifyAuthStatus.bind(null, request),

};

```

Use schema and context in your app

```js

const { graphql } = require('graphql');

graphql(schema, query, context)

  .then(result => console.log(result));

```

## Pagination

If given REST API response includes lists, we need to add page info and edge

connection cursors to handle pagination in GraphQL.

To handle this, the generated schema looks for `convertArrayToConnection` and

`parseCursorOptions` function definitions in `./array-to-connection.js`. SwagQL

provides a default implementation for array-to-connection. If your APIs return

pagination information in the response, the default implementation can be used

as follows:

```js

// array-to-connection.js

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

```

If your API responses handle pagination differently, you may have to customize

array-to-connection implementation.

## Acknowledgements

`test/fixtures/petstore.json` is taken from https://petstore.swagger.io/v2/swagger.json