|
| 1 | +[](https://travis-ci.org/yrashk/graphql-java-annotations) |
| 2 | +[](https://bintray.com/yrashk/graphql-java-annotations) |
| 3 | + |
| 4 | +# GraphQL Annotations for Java |
| 5 | + |
| 6 | +[GraphQL-Java](https://github.com/andimarek/graphql-java) is a great library, but its syntax is a little bit verbose. This library offers an annotations-based |
| 7 | +syntax for GraphQL schema definition. |
| 8 | + |
| 9 | +## Getting Started |
| 10 | + |
| 11 | + |
| 12 | +You can get packages from Bintray: |
| 13 | + |
| 14 | +(Gradle syntax) |
| 15 | + |
| 16 | +```groovy |
| 17 | +repositories { |
| 18 | + maven { |
| 19 | + url "http://dl.bintray.com/yrashk/maven" |
| 20 | + } |
| 21 | +} |
| 22 | +
|
| 23 | +dependencies { |
| 24 | + compile 'graphql-java-annotations:graphql-java-annotations:0.1.0' |
| 25 | +} |
| 26 | +``` |
| 27 | + |
| 28 | + |
| 29 | +## Defining Objects |
| 30 | + |
| 31 | +Any regular Java class can be converted to a GraphQL object type. Fields can |
| 32 | +be defined with a `@GraphQLField` (see more on fields below) annotation: |
| 33 | + |
| 34 | +```java |
| 35 | +public class SomeObject { |
| 36 | + @GraphQLField |
| 37 | + public String field; |
| 38 | +} |
| 39 | + |
| 40 | +// ... |
| 41 | +GraphQLObjectType object = GraphQLAnnotations.object(SomeObject.class); |
| 42 | +``` |
| 43 | + |
| 44 | +## Defining Interfaces |
| 45 | + |
| 46 | +This is very similar to defining objects: |
| 47 | + |
| 48 | +```java |
| 49 | +public interface SomeInterface { |
| 50 | + @GraphQLField |
| 51 | + String field(); |
| 52 | +} |
| 53 | + |
| 54 | +// ... |
| 55 | +GraphQLInterfaceType object = GraphQLAnnotations.iface(SomeInterface.class); |
| 56 | +``` |
| 57 | + |
| 58 | +## Fields |
| 59 | + |
| 60 | +In addition to specifying a field over a Java class field, a field can be defined over a method: |
| 61 | + |
| 62 | +```java |
| 63 | +public class SomeObject { |
| 64 | + @GraphQLField |
| 65 | + public String field() { |
| 66 | + return "field"; |
| 67 | + } |
| 68 | +} |
| 69 | +``` |
| 70 | + |
| 71 | +Or a method with arguments: |
| 72 | + |
| 73 | +```java |
| 74 | +public class SomeObject { |
| 75 | + @GraphQLField |
| 76 | + public String field(String value) { |
| 77 | + return value; |
| 78 | + } |
| 79 | +} |
| 80 | +``` |
| 81 | + |
| 82 | +You can also inject `DataFetchingEnvironment` as an argument, at any position: |
| 83 | + |
| 84 | +```java |
| 85 | +public class SomeObject { |
| 86 | + @GraphQLField |
| 87 | + public String field(DataFetchingEnvironment env, String value) { |
| 88 | + return value; |
| 89 | + } |
| 90 | +} |
| 91 | +``` |
| 92 | + |
| 93 | +Additionally, `@GraphQLName` can be used to override field name. You can use `@GraphQLDescription` to set a description. |
| 94 | + |
| 95 | +These can also be used for field parameters: |
| 96 | + |
| 97 | +```java |
| 98 | +public String field(@GraphQLName("val") String value) { |
| 99 | + return value; |
| 100 | +} |
| 101 | +``` |
| 102 | + |
| 103 | +In addition, `@GraphQLDefaultValue` can be used to set a default value to a parameter. Due to limitations of annotations, the default valueu has to be provided by a class that implements `Supplier<Object>`: |
| 104 | + |
| 105 | +```java |
| 106 | +public static class DefaultValue implements Supplier<Object> { |
| 107 | + @Override |
| 108 | + public Object get() { |
| 109 | + return "default"; |
| 110 | + } |
| 111 | +} |
| 112 | + |
| 113 | +@GraphQLField |
| 114 | +public String field(@GraphQLDefaultValue(DefaultValue.class) String value) { |
| 115 | + return value; |
| 116 | +} |
| 117 | +``` |
| 118 | + |
| 119 | +`@GraphQLDeprecate` and Java's `@Deprecated` can be used to specify a deprecated |
| 120 | +field. |
| 121 | + |
| 122 | +You can specify a custom data fetcher for a field with `@GraphQLDataFetcher` |
| 123 | + |
| 124 | +## Type Inference |
| 125 | + |
| 126 | +By default, standard GraphQL types (String, Integer, Long, Float, Boolean, Enum, List) will be inferred from Java types. Also, it will respect `@javax.validation.constraints.NotNull` annotation with respect to value's nullability. |
| 127 | + |
| 128 | +If you want to register an additional type (for example, UUID), you have to implement `TypeFunction` for it and register it with `DefaultTypeFunction`: |
| 129 | + |
| 130 | +```java |
| 131 | +DefaultTypeFunction.register(UUID.class, new UUIDTypeFunction()); |
| 132 | +``` |
| 133 | + |
| 134 | +You can also specify custom type function for any field with `@GraphQLType` annotation. |
0 commit comments