target / graphql-liftoff

Generate GraphQL schema language from API specifications and more

GraphQL Liftoff

graphql-liftoff is a GraphQL schema type generator. It takes in an existing data model and maps it to type definitions by using a domain specific parser. This reduces the amount of work needed to migrate existing REST APIs to GraphQL.

CLI Demo

demo YAML source

Roadmap

• Swagger 2.0 support
• 100% unit test code coverage
• CLI integration tests
• TypeDoc comments on all functions
• Swagger 1.0 support
• OpenAPI (Swagger 3.0) support
• RAML 1.0 support
• Your idea here!

Quick start

# CLI utility
npm install -g git+https://github.com/target/graphql-liftoff.git
yarn global add git+https://github.com/target/graphql-liftoff.git

# npm package
npm install git+https://github.com/target/graphql-liftoff.git
yarn add git+https://github.com/target/graphql-liftoff.git

# development
Fork this repo
git clone https://github.com/YourName/graphql-liftoff.git
cd graphql-liftoff
npm install or yarn

# scripts
build        # run typescript compiler
watch        # watch on file changes - then run typescript compiler
start <args> # run graphql-liftoff CLI locally
             # NOTE: npm strips out flags like -y or --yaml
             # yarn works as intended.
             # you can still manually run the commands:
             # node ./build/bin/cli.js <args>
lint         # run tslint
test         # run jest and generate coverage files
test:watch   # watch on file chages - then run jest
coverage     # open html coverage in browser (MacOS only)

Module Usage

graphql-liftoff exports an async generateSchema function, which returns a stringified Graphql Schema

await generateSchema('swagger', {'yaml': true, data: './example-swagger.yaml'}).then(schema => {
    console.log(schema)
}).catch(err => {
    console.error(err)
})

Bugs and Feature Requests

Found something that doesn't seem right or have a feature request? First, checkout our contribution guidelines, then open a new issue.

Contributors

A huge shoutout to all contributors and supporters of this project. THANK YOU!

Copyright and License

Copyright (c) 2017 Target Brands, Inc.

graphql-liftoff's Issues

Refactor Swagger CLI

Refactor Swagger CLI

Details

Since there is the goal of adding v1 v2 v3 support, instead of versioning out each Swagger instance, it's possible to refactor the existing swagger cli tool and identify the Swagger Version from the yaml/json file in order to determine which parser to use?

Additional Information

Essentially it would change the cli to only have a single swagger command, and the json/yaml file would dictate which parser to use inside of the service.

Issue Checklist

• Maintainer has viewed
• Loaded into Backlog
• PR submitted [Link Here](Eventual Link)

Setup code coverage visualization

Tenatively for now coveralls.

Add parameter to allow for prefixing all generated types

Please Add parameter to allow for prefixing all generated types

We are looking at using graphql-liftoff in conjunction with schema stitching from multiple swagger files and have some type naming collisions occurring. i.e. ...system1/api/user & system2/api/user in two separate swagger files both generate a User typeDef. We would like to suggest an optional parameter be added that allows for prefixing resulting generated typeDefs to prevent these collisions

100% unit test code coverage

installation fail on OSX High Sierra

Details

cannot install on OSX High Sierra

Additional Information

yarn global add git+https://github.com/target/graphql-liftoff.git
yarn global v1.9.4
warning package.json: No license field
[1/4] 🔍  Resolving packages...
warning git+https://github.com/target/graphql-liftoff.git > oas-raml-converter > raml-1-parser > [email protected]: wrench.js is deprecated! You should check out fs-extra (https://github.com/jprichardson/node-fs-extra) for any operations you were using wrench for. Thanks for all the usage over the years.
[2/4] 🚚  Fetching packages...
[3/4] 🔗  Linking dependencies...
warning "git+https://github.com/target/graphql-liftoff.git > [email protected]" has unmet peer dependency "babel-core@^6.0.0 || ^7.0.0-alpha || ^7.0.0-beta || ^7.0.0".
[4/4] 📃  Building fresh packages...
error /Users/shachar/.config/yarn/global/node_modules/graphql-liftoff: Command failed.
Exit code: 127
Command: node_modules/typescript/bin/tsc
Arguments: 
Directory: /Users/shachar/.config/yarn/global/node_modules/graphql-liftoff
Output:
/bin/sh: node_modules/typescript/bin/tsc: No such file or directory
info Visit https://yarnpkg.com/en/docs/cli/global for documentation about this command.

seems related to typesafe pre-requisite which i do not have.

Issue Checklist

• Maintainer has viewed

TypeDoc comments on all functions

Change in description comments to be string literals per GraphQL spec.

Change in description comments to be string literals per GraphQL spec.

Details

Per the spec in GraphQL code base:
/**

• Descriptions are defined as preceding string literals, however an older
• experimental version of the SDL supported preceding comments as
• descriptions. Set to true to enable this deprecated behavior.
• This option is provided to ease adoption and will be removed in v16.
• Default: false
  */

All description comments should be encapsulated around string literals, more specifically triple double quotes:
""" Description here """

Additional Information

I used your package to convert a swagger file from a third party API and there are a few things that needed to be done. This package does not recheck the return gql for malformations. I had to scan through the file and check to see if there was multi-line 'comments' and to rebuild it accordingly.

Link to comment in code base:
extendSchema#L47

Issue Checklist

• Maintainer has viewed
• Loaded into Backlog
• PR submitted [Link Here](Eventual Link)

OpenAPI (Swagger 3.0) support

RAML 1.0 support

Should be fairly easy - https://github.com/mulesoft/oas-raml-converter has support for RAML 1.0 - the underlying data model should be the same as the swagger 2.0 implementation

Migrate to @target-corp scoped NPM package

TODO

• Discovery on NPM package creation process
• Code changes to support new deployment process
• 🚀

wait

graphql-liftoff issue template replace with your issue title

Details

Provide a general statement here about the feature/bug/request
you have here

Additional Information

Provide any supporting documentation here. (Links to wiki, other sources, log output, etc.)

Issue Checklist

• Maintainer has viewed
• Loaded into Backlog
• PR submitted [Link Here](Eventual Link)

CLI integration tests

RAML 0.8 support

Should be fairly easy - https://github.com/mulesoft/oas-raml-converter has support for RAML 0.8 - the underlying data model should be the same as the swagger 2.0 implementation

Beef up documentation

• Add more information about how to make a parser
• Provide more insight into where such a tool like this has value

yiay

???

Swagger 1.0 support

Should be able to use https://github.com/apigee-127/swagger-converter and then feed it into the existing swagger 2.0 parser