{"id":13499402,"url":"https://github.com/bpatters/schemagen-graphql","last_synced_at":"2025-03-29T04:31:14.857Z","repository":{"id":54642018,"uuid":"50132488","full_name":"bpatters/schemagen-graphql","owner":"bpatters","description":"GraphQL-Java add-on that adds support for Schema Generation \u0026 Execution for enterprise level applications.","archived":false,"fork":false,"pushed_at":"2018-09-14T12:49:08.000Z","size":339,"stargazers_count":48,"open_issues_count":11,"forks_count":14,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-10-31T17:39:30.691Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bpatters.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-01-21T19:50:01.000Z","updated_at":"2024-08-24T09:57:43.000Z","dependencies_parsed_at":"2022-08-13T22:31:18.676Z","dependency_job_id":null,"html_url":"https://github.com/bpatters/schemagen-graphql","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bpatters%2Fschemagen-graphql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bpatters%2Fschemagen-graphql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bpatters%2Fschemagen-graphql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bpatters%2Fschemagen-graphql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bpatters","download_url":"https://codeload.github.com/bpatters/schemagen-graphql/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246140565,"owners_count":20729797,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T22:00:32.795Z","updated_at":"2025-03-29T04:31:14.348Z","avatar_url":"https://github.com/bpatters.png","language":"Java","funding_links":[],"categories":["Libraries","Implementations","Uncategorized","Schema Libraries"],"sub_categories":["Java Libraries","Java","Uncategorized","Code First"],"readme":"\u003e NOTE: I'm looking for users who would like to help maintain/improve this project. I haven't had the time to actively maintain this \u003erepository the past year and if someone would like to help update/mainain this repository I'd like to add you to the project. Join the gitter channel at https://gitter.im/schemagen-graphql/Lobby# and message me if interested.\n\nJava GraphQL Schema Generation and Execution Framework\n========\nThe versioning follows [Semantic Versioning](http://semver.org).\n[![CircleCI](https://circleci.com/gh/bpatters/schemagen-graphql.svg?style=svg)](https://circleci.com/gh/bpatters/schemagen-graphql)\n[![Latest Release](https://maven-badges.herokuapp.com/maven-central/com.bretpatterson/schemagen-graphql/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.bretpatterson/schemagen-graphql/)\n\n# Table of Contents\n- [Overview](#overview)\n- [Dependencies](#dependencies)\n- [Hello World](#hello-world)\n- [Basic Concepts](#basic-concepts)\n- [GraphQL Controllers](#graphql-controllers)\n- [Type Mappers](#type-mappers)\n- [Companies using in Production](#companies-using-in-production)\n\n### Overview\n\nThis is a java to GraphQL schema generation and execution package. This originated the week of January 18th, 2016 as a HackWeek \nproject I worked on.  The goal of this is a production level quality project that can be used to build\na Java based GraphQL server. \nThe following principles will guide this projects evolution:\n\n- An un-opinionated view of the container the server will use.\n- An un-opinionated view of the serialization model you will be using\n- Sensible defaults so that setup is extremely easy and straightforward\n- Extensible enough to handle the most extreme Enterprise scenarios\n- A minimal set of dependencies to utilize the framework.\n\nInitial Versions will have a base version of Java 7 and require the Guava Module. Future versions will possibly be based on Java 8 and\npossibly require the Guava module (TBD).\n\n### Dependencies\n\n- Guava (regardless if you include the guava type mapping package)\n- SLF4J (logging)\n- GraphQL-Java\n\n\n### Hello World\n\nThe Hello World program below is the simplest GraphQL server you can write. It exposes the GraphQL schema as a CLI\nthat you can run from the command line.\n\nHere is a simple hello world usage scenario\n\n```java\n\npackage com.bretpatterson.schemagen.graphql.examples;\n\nimport com.bretpatterson.schemagen.graphql.annotations.GraphQLQuery;\nimport com.bretpatterson.schemagen.graphql.annotations.GraphQLController;\nimport com.fasterxml.jackson.databind.ObjectMapper;\nimport com.google.common.collect.ImmutableList;\nimport com.bretpatterson.schemagen.graphql.GraphQLSchemaBuilder;\nimport com.bretpatterson.schemagen.graphql.examples.common.JacksonTypeFactory;\n\nimport graphql.ExecutionResult;\nimport graphql.GraphQL;\nimport graphql.schema.GraphQLSchema;\n\n/**\n * This is a hello world example of a graphQL query CLI\n */\n@GraphQLController\npublic class HelloWorld {\n\n\t@GraphQLQuery(name=\"helloWorld\")\n\tpublic String helloWorld() {\n\n\t\treturn \"Hello World!\";\n\t}\n\n\tpublic static void main(String[] args) throws Exception {\n\t\t// the object that we want to expose it's methods as queries\n\t\tHelloWorld helloWorld = new HelloWorld();\n\t\t// we use a Jackson object mapper object for serialization of values\n\t\tObjectMapper objectMapper = new ObjectMapper();\n\t\tGraphQLSchema schema = GraphQLSchemaBuilder.newBuilder()\n\t\t\t\t// register an object mappper so that parameter datatypes can be deserialized for method invocation\n\t\t\t\t.registerTypeFactory(new JacksonTypeFactory(objectMapper))\n\t\t\t\t// register the instance of Hello World as our query handler\n\t\t\t\t.registerGraphQLControllerObjects(ImmutableList.\u003cObject\u003eof(helloWorld))\n\t\t\t\t.build();\n\n\t\tString queryString = \"{ helloWorld }\";\n\n\t\tif (args.length \u003e 0) {\n\t\t\tqueryString = args[0];\n\t\t}\n\n\t\t// now lets execute a query against the schema\n\t\tExecutionResult result = new GraphQL(schema).execute(queryString);\n\t\tif (result.getErrors().size() != 0) {\n\t\t\t// if there are any errors serialize them using jackson and write them to stderr\n\t\t\tSystem.err.println(objectMapper.writeValueAsString(result.getErrors()));\n\t\t} else {\n\t\t\t// output your response as JSON serialized data\n\t\t\tSystem.out.println(objectMapper.writeValueAsString(result.getData()));\n\t\t}\n\t}\n}\n\n```\n### Basic Concepts\n\n\u003e GraphQL is a data query language and runtime designed and used at Facebook to request and deliver data to mobile and web apps since 2012.\n\nSchemagen GraphQL is a package that allows you to turn POJO's into a GraphQL Queryable set of objects. Typically these objects consist of two types:\n- Objects with methods that perform Queries or Mutations\n- Plain Data Objects used as return values and/or Parameters to Queries/Mutations.\n\nQueryable objects are POJO's where the class is annotated with [@GraphQLController](https://github.com/bpatters/schemagen-graphql/blob/master/src/main/java/com/bretpatterson/schemagen/graphql/annotations/GraphQLController.java) which signals that it contains methods annotated with [@GraphQLQuery](https://github.com/bpatters/schemagen-graphql/blob/master/src/main/java/com/bretpatterson/schemagen/graphql/annotations/GraphQLQuery.java) or [@GraphQLMutation](https://github.com/bpatters/schemagen-graphql/blob/master/src/main/java/com/bretpatterson/schemagen/graphql/annotations/GraphQLMutation.java). These objects have their annotated methods exposed as top level GraphQL fields as Queries or Mutations. \n\nPlain Data Objects are used to pass data back and forth between the server and the front end code. These require no annotations, but do need to be strongly typed and adhere to the limitations of GraphQL data types. For Java code this primarily means Maps must have Enum's as keys or must not be used at all. This is because Maps are transformed into objects as schema generation time and the keys must be a finite set of known possible values so they can be converted into property fields.\n\nSchemagen-GraphQL can convert most objects into sensible GraphQL data types, however, it sometimes needs help for objects that you need mapped in a custom manner. This is accomplished by writing custom [Type Mappers](#type-mappers).\n\n\nSensible defaults are provided for most things. However, there are a things that you must provide:\n- ITypeFactory \n-- You must provide an object that knows how to convert objects from GraphQL generic deserialized parameters into Java specific types. The examples package provides a simple [Jackson based Type Factory](https://github.com/bpatters/schemagen-graphql/blob/master/schemagen-graphql-examples/src/main/java/com/bretpatterson/schemagen/graphql/examples/common/JacksonTypeFactory.java).\n- [@GraphQLController annotated objects](https://github.com/bpatters/schemagen-graphql/blob/master/src/main/java/com/bretpatterson/schemagen/graphql/annotations/GraphQLController.java)\n-- with [@GraphQLQuery annotated methods](https://github.com/bpatters/schemagen-graphql/blob/master/src/main/java/com/bretpatterson/schemagen/graphql/annotations/GraphQLQuery.java)\n-- with [@GraphQLMutation annotated methods](https://github.com/bpatters/schemagen-graphql/blob/master/src/main/java/com/bretpatterson/schemagen/graphql/annotations/GraphQLMutation.java)\n\n\nTo build your schema you use the [GraphQLSchemaBuilder](https://github.com/bpatters/schemagen-graphql/blob/master/src/main/java/com/bretpatterson/schemagen/graphql/GraphQLSchemaBuilder.java) in conjunction with the required objects above. To create your GraphQL schema do the following:\n\n```java\n\nGraphQLSchemaBuilder schemaBuilder = GraphQLSchemaBuilder.newBuilder();\n\n// First register your Type Factory so your Schema knows how to convert query/mutation parameters received into java types.\nschemaBuilder.registerTypeFactory(new JacksonTypeFactory(objectMapper));\n\n// Next pass in a list of Controller objects that you want to use to expose Queries and Mutations through.\n// register the instance of Hello World as our query handler\n.registerGraphQLControllerObjects(ImmutableList.\u003cObject\u003eof(helloWorld))\n\n\n// Finally Build your GraphQL schema\nGraphQLSchema schema - schemaBuilder.build();\n```\n\nThat's all!\n\nNow it's up to you as to how you expose your schema to the outside world, but assuming you have a query string you want to execute within your schema you can run the schema using:\n\n```java\n\nExecutionResult result = new GraphQL(schema).execute(queryString);\n\n```\n\nThat's it! Any errors encountered can be obtained via ```result.getErrors()```  and your data results can be obtained via the ```result.getData()```.\n\n\n\n### GraphQL Controllers\n\nGraphQL Controllers are how you expose Top level Queries and Mutations via the GraphQL schema. These objects contain three types of annotations:\n[@GraphQLController ](https://github.com/bpatters/schemagen-graphql/blob/master/src/main/java/com/bretpatterson/schemagen/graphql/annotations/GraphQLController.java)\n-- with [@GraphQLQuery annotated methods](https://github.com/bpatters/schemagen-graphql/blob/master/src/main/java/com/bretpatterson/schemagen/graphql/annotations/GraphQLQuery.java)\n-- with [@GraphQLMutation annotated methods](https://github.com/bpatters/schemagen-graphql/blob/master/src/main/java/com/bretpatterson/schemagen/graphql/annotations/GraphQLMutation.java)\n\n#### @GraphQLController annotation\nThis annotation identifies the type as a controller and optionally specifies a rootObjectName to wrapper it's query in at the top level. \nFor example if you take the following class:\n\n```java \n\n@GraphQLController\npublic class KeyValueStoreController {\n  @GraphQLIgnore\n  private Map\u003cString,String\u003e dataStore;\n  \n  @GraphQLQuery(name=\"get\")\n  public String getValue(String key) {\n     return dataStore.get(key);\n  }\n  \n  @GraphQLMutation(name=\"put\")\n  public String setValue(String key, String value) {\n  \tdataStore.put(key,value);\n  \t\n  \treturn value;\n  }\n}\n```\n\nThis class exposes a simple key -\u003e value store via GraphQL. There is one query operation, get, and one mutation operation named put. The ```@GraphQLQuery``` and ```@GraphQLMutation``` annotations by default will name the filed the name of the method. However in this case we have chosen to rename the field exposed for the query and mutations respectively to \"get\" and \"put\". \n\nYou can then store key/values using:\n```mutation Store { put(key:\"key1\", value:\"value1\") }```\nwhich outputs: ```{\"put\":\"value1\"}```\n\nYou could then retrieve the value with:\n```query MyQuery { get(key:\"key1\") }```\nwhich outputs: ```{\"get\":\"value1\"}```\n\nYou can also do schema queries like:\n``` \n{\n  __schema {\n    queryType {\n      name,\n      fields {\n        name\n      }\n    }\n  }\n}\n```\n\nwhich outputs:\n```json\n{\n  \"__schema\": {\n    \"queryType\": {\n      \"name\": \"Query\",\n      \"fields\": [\n        {\n          \"name\": \"node\"\n        },\n        {\n          \"name\": \"get\"\n        }\n      ]\n    }\n  }\n```\n\n# Companies using in Production\nThe following companies have been using in production\n\n- Spredfast\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbpatters%2Fschemagen-graphql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbpatters%2Fschemagen-graphql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbpatters%2Fschemagen-graphql/lists"}