mstachniuk / graphql-schema-from-introspection-generator

GraphQL Schema from Introspection generator

GraphQL Schema from Introspection generator

This library helps you generate GraphQL Schema (also called GraphQL DSL or SDL) based on Introspection Query response. It's useful when you use graphql-java and Code First approach and want to migrate to Schema First approach.

How to use it?

1. Download Command Line Tool from releases page.

2. Run java -jar graphql-schema-from-introspection-generator-cli-X.X.X.jar input.json output.graphqls

   File input.json should contain the output of GrpahQL Introspection query. If you don't have this file yet, you can use one from: core/src/test/resources/testdata/

3. In output.graphqls you will find generated GraphQL Schema.

How get Introspection Query result?

1. Run your application.

2. Run

   Introspection Query

       query IntrospectionQuery {
         __schema {
           queryType { name }
           mutationType { name }
           subscriptionType { name }
           types {
             ...FullType
           }
           directives {
             name
             description
             locations
             args {
               ...InputValue
             }
           }
         }
       }
     
       fragment FullType on __Type {
         kind
         name
         description
         fields(includeDeprecated: true) {
           name
           description
           args {
             ...InputValue
           }
           type {
             ...TypeRef
           }
           isDeprecated
           deprecationReason
         }
         inputFields {
           ...InputValue
         }
         interfaces {
           ...TypeRef
         }
         enumValues(includeDeprecated: true) {
           name
           description
           isDeprecated
           deprecationReason
         }
         possibleTypes {
           ...TypeRef
         }
       }
     
       fragment InputValue on __InputValue {
         name
         description
         type { ...TypeRef }
         defaultValue
       }
     
       fragment TypeRef on __Type {
         kind
         name
         ofType {
           kind
           name
           ofType {
             kind
             name
             ofType {
               kind
               name
               ofType {
                 kind
                 name
                 ofType {
                   kind
                   name
                   ofType {
                     kind
                     name
                     ofType {
                       kind
                       name
                     }
                   }
                 }
               }
             }
           }
         }
       }
   

   This query based on Introspection Queries in graphql-java and GraphiQL projects.

3. Store result in a file and use Command Line tool for generating the schema (See: How to use it?).

Release Notes

Release notes: docs/release-notes.md

How to build project?

1. Clone repo
2. Run ./gradlew build
3. You can find Command Line Tool in cli/build/libs
4. You can find core library in core/build/libs

Another usage

You can use the core library in your projects if you want. Just add a dependency (in Gradle):

compile group: 'io.github.mstachniuk', name: 'graphql-schema-from-introspection-generator-core'

How to contribute?

Please Send PR's, issues and feedback via GitHub.

Alternatives

During finishing this project I found that similar tool already exists in graphql-java project, see IntrospectionResultToSchema class.

Another possibility is to use graphql-js and this code snippet (NodeJS):

const graphql = require("graphql");
const schema = require("path/to/schema.json");

const clientSchema = graphql.buildClientSchema(schema.data);
const schemaString = graphql.printSchema(clientSchema);
console.log(schemaString)

Unfortunately, I didn't know that before :-(

graphql-schema-from-introspection-generator's Issues

Add support for default values in arguments of operations in Queries and Mutations

Default values of arguments are ignored. Introspection query for this schema:

type Mutation {
    createCircle(latitude: Float!, longitude: Float!, radius: Int = 10000): Circle
}

type Query {
    findHotel(latitude: Float!, longitude: Float!, radius: Int = 10000): [Hotel]
}

Will generate:

type Mutation {
    createCircle(latitude: Float!, longitude: Float!, radius: Int): Circle
}

type Query {
    findHotel(latitude: Float!, longitude: Float!, radius: Int): [Hotel]
}

Auto mocking scalars interfaces and unions in tests

Add support in GraphQLServer for discovering scalars interfaces and unions and mock automatically scalars unions and interfaces to avoid SchemaProblems.

Error: SchemaProblem{errors=[There is no top level schema object defined, There is no scalar implementation for the named 'Double' scalar type, There is no type resolver defined for interface / union 'SomeInterface' type, There is no type resolver defined for interface / union 'UserOrUserGroup' type]}

Example to reproduce:

scalar Double

interface SomeInterface {
    # The unique identifier
    id: ID
    max: Int
    min: Int
}

union UserOrUserGroup = User | UserGroup

type User {
    id: ID
    name: String
}

type UserGroup {
    id: ID
    groupName: String
}

Suport custom schema query

This schema:

schema {
    query: QueryType
    mutation: MutationType
    subscription: SubscriptionType
}

type QueryType {
    hero(episode: String): String
}

type MutationType {
    createHero(name: String): String
}

type SubscriptionType {
    subHero(name: String) : String
}

will miss schema node in schema produced by Generator.
This entries from Introspection query are ignored:

      "subscriptionType": {
        "name": "SubscriptionType"
      },
      "mutationType": {
        "name": "MutationType"
      },
      "queryType": {
        "name": "QueryType"
      }

Add support for descriptions

Comments are now ignored, descriptions should be used. It should be configurable.

More info:
https://github.com/mstachniuk/graphql-schema-from-introspection-generator/issues

Parse scalars description

Scalar's description is not parsed, e.g.:

schema {
    query: QueryType
}

type QueryType {
    hero(episode: String): SomeID
}

# SomeID description
scalar SomeID

The scalar's comment after -> JSON -> Schema is lost.

Add test for easier discovery if schema generation works

Now tests only takes Introspection Query result, generate Schema and compare with expected Schema.
It would be nice to have a test that takes GraphQL Schema, generate Introspection Query result, pass it to the Generator and compare with input Schema. This kind of test will improve validating of this tool.

Comments shouldn't start from space

because graphql-java put this space in description fields.

Example:

type Customer {
    # unique id
    id: ID!
}

will produce in introspection query:

"description": " unique id"

what can be confusing during comparing introspection queries

Comments shouldn't be trimmed at end by default

type Customer {
    # fields with ! are required   
    id: ID!
    name: String
}

type Query {
    customer(id: String!): Customer!
}

Add support for directives in schema

Currently directives are not supported by generator, but should be. Here is an example of usage:

directive @schemaDirective on SCHEMA

# Custom Scalar Directive
directive @scalardirective on SCALAR

directive @objectDirective on OBJECT

directive @auth(role : String!) on FIELD_DEFINITION

# Directive comment
directive @unique on FIELD_DEFINITION

directive @arg on ARGUMENT_DEFINITION

directive @interfaceDirective on INTERFACE

directive @unionDirective on UNION

directive @enumdir on ENUM

directive @enumVal on ENUM_VALUE

directive @inputObj on INPUT_OBJECT

directive @inputField on INPUT_FIELD_DEFINITION



input CreateCustomerInput @inputObj {
    clientMutationId: String!
    email: String @inputField
    name: String
}

type Customer {
    id: ID! @unique
    name: String @auth(role : "manager")
    map: MyMap
}

type Mutation {
    createCustomer(input: CreateCustomerInput) : Customer
}

scalar MyMap @scalardirective

type Query {
    customer(id: String @arg): Customer
}

interface SomeInterface @interfaceDirective {
    # The unique identifier
    id: ID
    max: Int
    min: Int
}

enum Status @enumdir {
    NEW, CANCELED, DONE @enumVal
}

type User {
    id: ID
    name: String
}

type UserGroup {
    groupName: String
    id: ID
}

union UserOrUserGroup @unionDirective = User | UserGroup