From 2e045b7f59e68ec2c934bcec7aa0af9040955569 Mon Sep 17 00:00:00 2001
From: Bogdan Kobylynskyi <92bogdan@gmail.com>
Date: Thu, 28 May 2020 07:08:25 -0500
Subject: [PATCH] Externalize codegen options to a separate file (#156)
* Externalize codegen options to a separate file
* Update codegen-options.md
---
docs/codegen-options.md | 77 +++++++++++++++++++++++++++++++++++++++
plugins/gradle/README.md | 77 +--------------------------------------
plugins/maven/README.md | 78 +---------------------------------------
3 files changed, 79 insertions(+), 153 deletions(-)
create mode 100644 docs/codegen-options.md
diff --git a/docs/codegen-options.md b/docs/codegen-options.md
new file mode 100644
index 00000000..0b696bd3
--- /dev/null
+++ b/docs/codegen-options.md
@@ -0,0 +1,77 @@
+# Codegen Options
+
+| Option | Data Type | Default value | Description |
+| :---------------------------------------------: | :------------------------------------------------: | :-------------------------------------------: | ----------- |
+| `graphqlSchemaPaths` | List(String) | (falls back to `graphqlSchemas`) | GraphQL schema locations. You can supply multiple paths to GraphQL schemas. To include many schemas from a folder hierarchy, use the `graphqlSchemas` block instead. |
+| `graphqlSchemas` | *See [graphqlSchemas](#option-graphqlschemas)* | All `.graphqls`/`.graphql` files in resources | Block to define the input GraphQL schemas, when exact paths are too cumbersome. See table below for a list of options. |
+| `outputDir` | String | None | The output target directory into which code will be generated. |
+| `jsonConfigurationFile` | String | Empty | Path to an external mapping configuration. |
+| `packageName` | String | Empty | Java package for generated classes. |
+| `apiPackageName` | String | Empty | Java package for generated api classes (Query, Mutation, Subscription). |
+| `modelPackageName` | String | Empty | Java package for generated model classes (type, input, interface, enum, union). |
+| `generateBuilder` | Boolean | True | Specifies whether generated model classes should have builder. |
+| `generateApis` | Boolean | True | Specifies whether api classes should be generated as well as model classes. |
+| `generateAsyncApi` | Boolean | False | If true, then wrap type into `java.util.concurrent.CompletableFuture` or `subscriptionReturnType` |
+| `generateDataFetchingEnvironmentArgumentInApis` | Boolean | False | If true, then `graphql.schema.DataFetchingEnvironment env` will be added as a last argument to all methods of root type resolvers and field resolvers. |
+| `generateEqualsAndHashCode` | Boolean | False | Specifies whether generated model classes should have equals and hashCode methods defined. |
+| `generateToString` | Boolean | False | Specifies whether generated model classes should have toString method defined. |
+| `modelNamePrefix` | String | Empty | Sets the prefix for GraphQL model classes (type, input, interface, enum, union). |
+| `modelNameSuffix` | String | Empty | Sets the suffix for GraphQL model classes (type, input, interface, enum, union). |
+| `modelValidationAnnotation` | String | @javax.validation.
constraints.NotNull | Annotation for mandatory (NonNull) fields. Can be null/empty. |
+| `customTypesMapping` | Map(String,String) | Empty | Can be used to supply custom mappings for scalars.
Supports:
* Map of (GraphqlObjectName.fieldName) to (JavaType)
* Map of (GraphqlType) to (JavaType) |
+| `customAnnotationsMapping` | Map(String,String) | Empty | Can be used to supply custom annotations (serializers) for scalars.
Supports:
* Map of (GraphqlObjectName.fieldName) to (JavaAnnotation)
* Map of (GraphqlType) to (JavaAnnotation) |
+| `fieldsWithResolvers` | Set(String) | Empty | Fields that require Resolvers should be defined here in format: `TypeName.fieldName` or `TypeName`. |
+| `fieldsWithoutResolvers` | Set(String) | Empty | Fields that DO NOT require Resolvers should be defined here in format: `TypeName.fieldName` or `TypeName`. Can be used in conjunction with `generateExtensionFieldsResolvers` option. |
+| `generateParameterizedFieldsResolvers` | Boolean | True | If true, then generate separate `Resolver` interface for parametrized fields. If false, then add field to the type definition and ignore field parameters. |
+| `generateExtensionFieldsResolvers` | Boolean | False | Specifies whether all fields in extensions (`extend type` and `extend interface`) should be present in Resolver interface instead of the type class itself. |
+| `subscriptionReturnType` | String | Empty | Return type for subscription methods. For example: `org.reactivestreams.Publisher`, `io.reactivex.Observable`, etc. |
+| `generateRequests` | Boolean | False | Specifies whether client-side classes should be generated for each query, mutation and subscription. This includes: `Request` class (contains input data) and `ResponseProjection` class (contains response fields). |
+| `requestSuffix` | String | Request | Sets the suffix for `Request` classes. |
+| `responseProjectionSuffix` | String | ResponseProjection | Sets the suffix for `ResponseProjection` classes. |
+| `parametrizedInputSuffix` | String | ParametrizedInput | Sets the suffix for `ParametrizedInput` classes. |
+| `parentInterfaces` | *See [parentInterfaces](#option-parentinterfaces)* | Empty | Block to define parent interfaces for generated interfaces (query / mutation / subscription / type resolver) |
+
+
+### Option `graphqlSchemas`
+
+When exact paths to GraphQL schemas are too cumbersome to provide in the `graphqlSchemaPaths`, use the `graphqlSchemas` block.
+The parameters inside that block are the following:
+
+| Key inside `graphqlSchemas` | Data Type | Default value | Description |
+| --------------------------- | ------------ | ------------------ | ----------- |
+| `rootDir` | String | Main resources dir | The root directory from which to start searching for schema files. |
+| `recursive` | Boolean | `true` | Whether to recursively look into sub directories. |
+| `includePattern` | String | `.*\.graphqls?` | A Java regex that file names must match to be included. It should be a regex as defined by the [Pattern](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) JDK class. It will be used to match only the file name without path. |
+| `excludedFiles` | Set | (empty set) | A set of files to exclude, even if they match the include pattern. These paths should be either absolute or relative to the provided `rootDir`. |
+
+
+### Option `parentInterfaces`
+
+Following options can be defined if you want generated resolvers to extend certain interfaces.
+Can be handy if you are using [graphql-java-tools](https://github.com/graphql-java-kickstart/graphql-java-tools) and want your resolver classes to extend only interfaces generated by this plugin.
+
+**Note:** if you want to include a GraphQL type name into the interface name, then use `{{TYPE}}` placeholder. E.g.: `graphql.kickstart.tools.GraphQLResolver<{{TYPE}}>`
+
+| Key inside `parentInterfaces` | Data Type | Default value | Description |
+| ----------------------------- | --------- | ------------- | ----------- |
+| `queryResolver` | String | Empty | Interface that will be added as "extend" to all generated api Query interfaces. |
+| `mutationResolver` | String | Empty | Interface that will be added as "extend" to all generated api Mutation interfaces. |
+| `subscriptionResolver` | String | Empty | Interface that will be added as "extend" to all generated api Subscription interfaces. |
+| `resolver` | String | Empty | Interface that will be added as "extend" to all generated TypeResolver interfaces. |
+
+
+
+#### External mapping configuration
+
+Provide a path to external file via property `jsonConfigurationFile`
+Sample content of the file:
+
+```json
+{
+ "generateApis": true,
+ "packageName": "com.kobylynskyi.graphql.testconfigjson",
+ "customTypesMapping": {
+ "Price.amount": "java.math.BigDecimal"
+ }
+}
+```
\ No newline at end of file
diff --git a/plugins/gradle/README.md b/plugins/gradle/README.md
index af7b8cfa..310b4dd8 100644
--- a/plugins/gradle/README.md
+++ b/plugins/gradle/README.md
@@ -54,66 +54,7 @@ apply plugin: "io.github.kobylynskyi.graphql.codegen"
### Plugin Options
-| Option | Data Type | Default value | Description |
-| :---------------------------------------------: | :------------------------------------------------: | :-------------------------------------------: | ----------- |
-| `graphqlSchemaPaths` | List(String) | (falls back to `graphqlSchemas`) | GraphQL schema locations. You can supply multiple paths to GraphQL schemas. To include many schemas from a folder hierarchy, use the `graphqlSchemas` block instead. |
-| `graphqlSchemas` | *See [graphqlSchemas](#option-graphqlschemas)* | All `.graphqls`/`.graphql` files in resources | Block to define the input GraphQL schemas, when exact paths are too cumbersome. See table below for a list of options. |
-| `outputDir` | String | None | The output target directory into which code will be generated. |
-| `jsonConfigurationFile` | String | Empty | Path to an external mapping configuration. |
-| `packageName` | String | Empty | Java package for generated classes. |
-| `apiPackageName` | String | Empty | Java package for generated api classes (Query, Mutation, Subscription). |
-| `modelPackageName` | String | Empty | Java package for generated model classes (type, input, interface, enum, union). |
-| `generateBuilder` | Boolean | True | Specifies whether generated model classes should have builder. |
-| `generateApis` | Boolean | True | Specifies whether api classes should be generated as well as model classes. |
-| `generateAsyncApi` | Boolean | False | If true, then wrap type into `java.util.concurrent.CompletableFuture` or `subscriptionReturnType` |
-| `generateDataFetchingEnvironmentArgumentInApis` | Boolean | False | If true, then `graphql.schema.DataFetchingEnvironment env` will be added as a last argument to all methods of root type resolvers and field resolvers. |
-| `generateEqualsAndHashCode` | Boolean | False | Specifies whether generated model classes should have equals and hashCode methods defined. |
-| `generateToString` | Boolean | False | Specifies whether generated model classes should have toString method defined. |
-| `modelNamePrefix` | String | Empty | Sets the prefix for GraphQL model classes (type, input, interface, enum, union). |
-| `modelNameSuffix` | String | Empty | Sets the suffix for GraphQL model classes (type, input, interface, enum, union). |
-| `modelValidationAnnotation` | String | @javax.validation.
constraints.NotNull | Annotation for mandatory (NonNull) fields. Can be null/empty. |
-| `customTypesMapping` | Map(String,String) | Empty | Can be used to supply custom mappings for scalars.
Supports:
* Map of (GraphqlObjectName.fieldName) to (JavaType)
* Map of (GraphqlType) to (JavaType) |
-| `customAnnotationsMapping` | Map(String,String) | Empty | Can be used to supply custom annotations (serializers) for scalars.
Supports:
* Map of (GraphqlObjectName.fieldName) to (JavaAnnotation)
* Map of (GraphqlType) to (JavaAnnotation) |
-| `fieldsWithResolvers` | Set(String) | Empty | Fields that require Resolvers should be defined here in format: `TypeName.fieldName` or `TypeName`. |
-| `fieldsWithoutResolvers` | Set(String) | Empty | Fields that DO NOT require Resolvers should be defined here in format: `TypeName.fieldName` or `TypeName`. Can be used in conjunction with `generateExtensionFieldsResolvers` option. |
-| `generateParameterizedFieldsResolvers` | Boolean | True | If true, then generate separate `Resolver` interface for parametrized fields. If false, then add field to the type definition and ignore field parameters. |
-| `generateExtensionFieldsResolvers` | Boolean | False | Specifies whether all fields in extensions (extend type and extend interface) should be present in Resolver interface instead of the type class itself. |
-| `subscriptionReturnType` | String | Empty | Return type for subscription methods. For example: `org.reactivestreams.Publisher`, `io.reactivex.Observable`, etc. |
-| `generateRequests` | Boolean | False | Specifies whether client-side classes should be generated for each query, mutation and subscription. This includes: `Request` class (contains input data) and `ResponseProjection` class (contains response fields). |
-| `requestSuffix` | String | Request | Sets the suffix for `Request` classes. |
-| `responseProjectionSuffix` | String | ResponseProjection | Sets the suffix for `ResponseProjection` classes. |
-| `parametrizedInputSuffix` | String | ParametrizedInput | Sets the suffix for `ParametrizedInput` classes. |
-| `parentInterfaces` | *See [parentInterfaces](#option-parentinterfaces)* | Empty | Block to define parent interfaces for generated interfaces (query / mutation / subscription / type resolver) |
-
-
-#### Option `graphqlSchemas`
-
-When exact paths to GraphQL schemas are too cumbersome to provide in the `graphqlSchemaPaths`, use the `` block.
-The parameters inside that block are the following:
-
-| Key inside `graphqlSchemas` | Data Type | Default value | Description |
-| --------------------------- | ------------ | ------------------ | ----------- |
-| `rootDir` | String | Main resources dir | The root directory from which to start searching for schema files. |
-| `recursive` | Boolean | `true` | Whether to recursively look into sub directories. |
-| `includePattern` | String | `.*\.graphqls?` | A Java regex that file names must match to be included. It should be a regex as defined by the [Pattern](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) JDK class. It will be used to match only the file name without path. |
-| `excludedFiles` | Set | (empty set) | A set of files to exclude, even if they match the include pattern. These paths should be either absolute or relative to the provided `rootDir`. |
-
-
-#### Option `parentInterfaces`
-
-Following options can be defined if you want generated resolvers to extend certain interfaces.
-Can be handy if you are using [graphql-java-tools](https://github.com/graphql-java-kickstart/graphql-java-tools) and want your resolver classes to extend only interfaces generated by this plugin.
-
-**Note:** if you want to include a GraphQL type name into the interface name, then use `{{TYPE}}` placeholder. E.g.: `graphql.kickstart.tools.GraphQLResolver<{{TYPE}}>`
-
-| Key inside `parentInterfaces` | Data Type | Default value | Description |
-| ----------------------------- | --------- | ------------- | ----------- |
-| `queryResolver` | String | Empty | Interface that will be added as "extend" to all generated api Query interfaces. |
-| `mutationResolver` | String | Empty | Interface that will be added as "extend" to all generated api Mutation interfaces. |
-| `subscriptionResolver` | String | Empty | Interface that will be added as "extend" to all generated api Subscription interfaces. |
-| `resolver` | String | Empty | Interface that will be added as "extend" to all generated TypeResolver interfaces. |
-
-
+Please refer to [Codegen Options](../../docs/codegen-options.md)
### Sample Plugin Configuration
@@ -168,22 +109,6 @@ check.dependsOn(graphqlCodegen)
```
-#### External mapping configuration
-
-Provide a path to external file via property `jsonConfigurationFile`
-Sample content of the file:
-
-```json
-{
- "generateApis": true,
- "packageName": "com.kobylynskyi.graphql.testconfigjson",
- "customTypesMapping": {
- "Price.amount": "java.math.BigDecimal"
- }
-}
-```
-
-
### Examples
#### GraphQL **server** code generation
diff --git a/plugins/maven/README.md b/plugins/maven/README.md
index b58f1da3..c59faf4e 100644
--- a/plugins/maven/README.md
+++ b/plugins/maven/README.md
@@ -66,83 +66,7 @@ You can run the plugin manually with `mvn generate-sources`. It will be run auto
### Plugin Options
-| Option | Data Type | Default value | Description |
-| :---------------------------------------------: | :------------------------------------------------: | :-------------------------------------------: | ----------- |
-| `graphqlSchemaPaths` | List(String) | (falls back to `graphqlSchemas`) | GraphQL schema locations. You can supply multiple paths to GraphQL schemas. To include many schemas from a folder hierarchy, use the `graphqlSchemas` block instead. |
-| `graphqlSchemas` | *See [graphqlSchemas](#option-graphqlschemas)* | All `.graphqls`/`.graphql` files in resources | Block to define the input GraphQL schemas, when exact paths are too cumbersome. See table below for a list of options. |
-| `outputDir` | String | None | The output target directory into which code will be generated. |
-| `jsonConfigurationFile` | String | Empty | Path to an external mapping configuration. |
-| `packageName` | String | Empty | Java package for generated classes. |
-| `apiPackageName` | String | Empty | Java package for generated api classes (Query, Mutation, Subscription). |
-| `modelPackageName` | String | Empty | Java package for generated model classes (type, input, interface, enum, union). |
-| `generateBuilder` | Boolean | True | Specifies whether generated model classes should have builder. |
-| `generateApis` | Boolean | True | Specifies whether api classes should be generated as well as model classes. |
-| `generateAsyncApi` | Boolean | False | If true, then wrap type into `java.util.concurrent.CompletableFuture` or `subscriptionReturnType` |
-| `generateDataFetchingEnvironmentArgumentInApis` | Boolean | False | If true, then `graphql.schema.DataFetchingEnvironment env` will be added as a last argument to all methods of root type resolvers and field resolvers. |
-| `generateEqualsAndHashCode` | Boolean | False | Specifies whether generated model classes should have equals and hashCode methods defined. |
-| `generateToString` | Boolean | False | Specifies whether generated model classes should have toString method defined. |
-| `modelNamePrefix` | String | Empty | Sets the prefix for GraphQL model classes (type, input, interface, enum, union). |
-| `modelNameSuffix` | String | Empty | Sets the suffix for GraphQL model classes (type, input, interface, enum, union). |
-| `modelValidationAnnotation` | String | @javax.validation.
constraints.NotNull | Annotation for mandatory (NonNull) fields. Can be null/empty. |
-| `customTypesMapping` | Map(String,String) | Empty | Can be used to supply custom mappings for scalars.
Supports:
* Map of (GraphqlObjectName.fieldName) to (JavaType)
* Map of (GraphqlType) to (JavaType) |
-| `customAnnotationsMapping` | Map(String,String) | Empty | Can be used to supply custom annotations (serializers) for scalars.
Supports:
* Map of (GraphqlObjectName.fieldName) to (JavaAnnotation)
* Map of (GraphqlType) to (JavaAnnotation) |
-| `fieldsWithResolvers` | Set(String) | Empty | Fields that require Resolvers should be defined here in format: `TypeName.fieldName` or `TypeName`. |
-| `fieldsWithoutResolvers` | Set(String) | Empty | Fields that DO NOT require Resolvers should be defined here in format: `TypeName.fieldName` or `TypeName`. Can be used in conjunction with `generateExtensionFieldsResolvers` option. |
-| `generateParameterizedFieldsResolvers` | Boolean | True | If true, then generate separate `Resolver` interface for parametrized fields. If false, then add field to the type definition and ignore field parameters. |
-| `generateExtensionFieldsResolvers` | Boolean | False | Specifies whether all fields in extensions (extend type and extend interface) should be present in Resolver interface instead of the type class itself. |
-| `subscriptionReturnType` | String | Empty | Return type for subscription methods. For example: `org.reactivestreams.Publisher`, `io.reactivex.Observable`, etc. |
-| `generateRequests` | Boolean | False | Specifies whether client-side classes should be generated for each query, mutation and subscription. This includes: `Request` class (contains input data) and `ResponseProjection` class (contains response fields). |
-| `requestSuffix` | String | Request | Sets the suffix for `Request` classes. |
-| `responseProjectionSuffix` | String | ResponseProjection | Sets the suffix for `ResponseProjection` classes. |
-| `parametrizedInputSuffix` | String | ParametrizedInput | Sets the suffix for `ParametrizedInput` classes. |
-| `parentInterfaces` | *See [parentInterfaces](#option-parentinterfaces)* | Empty | Block to define parent interfaces for generated interfaces (query / mutation / subscription / type resolver) |
-
-
-#### Option `graphqlSchemas`
-
-When exact paths to GraphQL schemas are too cumbersome to provide in the `graphqlSchemaPaths`, use the `` block.
-The parameters inside that block are the following:
-
-| Key inside `graphqlSchemas` | Data Type | Default value | Description |
-| --------------------------- | ------------ | ------------------ | ----------- |
-| `rootDir` | String | Main resources dir | The root directory from which to start searching for schema files. |
-| `recursive` | Boolean | `true` | Whether to recursively look into sub directories. |
-| `includePattern` | String | `.*\.graphqls?` | A Java regex that file names must match to be included. It should be a regex as defined by the [Pattern](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) JDK class. It will be used to match only the file name without path. |
-| `excludedFiles` | Set | (empty set) | A set of files to exclude, even if they match the include pattern. These paths should be either absolute or relative to the provided `rootDir`. |
-
-
-#### Option `parentInterfaces`
-
-Following options can be defined if you want generated resolvers to extend certain interfaces.
-Can be handy if you are using [graphql-java-tools](https://github.com/graphql-java-kickstart/graphql-java-tools) and want your resolver classes to extend only interfaces generated by this plugin.
-
-**Note:** if you want to include a GraphQL type name into the interface name, then use `{{TYPE}}` placeholder. E.g.: `graphql.kickstart.tools.GraphQLResolver<{{TYPE}}>`
-
-
-| Key inside `parentInterfaces` | Data Type | Default value | Description |
-| ----------------------------- | --------- | ------------- | ----------- |
-| `queryResolver` | String | Empty | Interface that will be added as "extend" to all generated api Query interfaces. |
-| `mutationResolver` | String | Empty | Interface that will be added as "extend" to all generated api Mutation interfaces. |
-| `subscriptionResolver` | String | Empty | Interface that will be added as "extend" to all generated api Subscription interfaces. |
-| `resolver` | String | Empty | Interface that will be added as "extend" to all generated TypeResolver interfaces. |
-
-
-
-#### External mapping configuration
-
-Provide a path to external file via property `jsonConfigurationFile`
-Sample content of the file:
-
-```json
-{
- "generateApis": true,
- "packageName": "com.kobylynskyi.graphql.testconfigjson",
- "customTypesMapping": {
- "Price.amount": "java.math.BigDecimal"
- }
-}
-```
-
+Please refer to [Codegen Options](../../docs/codegen-options.md)
### Examples
--
GitLab