Docs
Launch GraphOS Studio

Codegen configuration


The Code Generation Engine is flexible and can be configured for different behaviors.

The configuration options for code generation are represented by the ApolloCodegenConfiguration struct.

When using the Codegen CLI, your configuration is represented by the apollo-codegen-configuration.json JSON file created by the CLI's init command.

When running code generation in your own Swift code, the configuration options are represented by the ApolloCodegenConfiguration struct.

Most of the configuration properties have defaults that provide a good starting point.

There are a number of base configuration properties, each representing a specific characteristic of the codegen engine:

Property NameDescription
schemaNamespaceNamespace used to scope the generated schema types.
inputSearch patterns that will be used to locate the schema and operation definition files.
outputLocation and structure of the generated files and modules.
optionsRules and options to customize the generated code.
experimentalFeaturesUsed to enable experimental features.
Note: These features could change at any time and are not guaranteed to always be available.
schemaDownloadConfiguration to fetch a GraphQL schema before generation.
operationManifestConfiguration to generate operation manifests for persisted queries

Schema namespace

schemaNamespace: String

This option defines the name of your schema module or namespace.

Along with your definitions, generates a set of metadata objects that represent the types in your schema. All of these object are grouped within a namespace with the provided name.

  • If you are embedding your generated schema types within another target, this will be the name of a caseless namespace enum.

  • If you are including your schema types as a stand-alone target that can be imported by your other project targets, this will be the name of that target.

You can configure how you would like to include your schema types in your project using the output.schemaTypes.moduleType option.

File input

input: FileInput

The code generation engine requires a and at least one to be able to generate Swift code. Read the introductory section on GraphQL source files for more information.

The properties to configure input are:

Property NameDescription
schemaSearchPathsAn array of path matching pattern strings used to find GraphQL schema files. Schema extension files can be included in these search paths.

Note: JSON format schema files must have the .json file extension.
operationSearchPathsAn array of path matching pattern strings used to find GraphQL operation files.
CLI Configuration JSON
"input": {
"schemaSearchPaths": [
"**/*.graphqls"
],
"operationSearchPaths": [
"**/*.graphql"
]
}
Swift Codegen Setup
let configuration = ApolloCodegenConfiguration(
// Other properties not shown
input: ApolloCodegenConfiguration.FileInput(
schemaSearchPaths: ["**/*.graphqls"],
operationSearchPaths: ["**/*.graphql"]
),
)

Search Path Patterns

Each file input property is a [String] search path array. Search paths can be used to search your project directory for files matching a glob pattern. You can use absolute or relative paths in path matching patterns. Relative paths will be based off the current working directory.

Each path matching pattern can include the following characters:

  • * matches everything but the directory separator (shallow), eg: *.graphql
  • ? matches any single character, eg: file-?.graphql
  • ** matches all subdirectories (deep), eg: **/*.graphql
  • ! excludes any match only if the pattern starts with a ! character, eg: !file.graphql

File output

output: FileOutput

The FileOutput options are used to configure which files are generated and their output locations.

The properties to configure output are:

Property NameDescription
schemaTypesLocation and structure of the generated schema types files.
operationsLocation and structure of the generated operation files such as queries, mutations, subscriptions, and fragments.
testMocksLocation and structure of the test mock operation object files.

If .none, test mocks will not be generated.
CLI Configuration JSON
"output": {
"schemaTypes": {
"moduleType": {
"swiftPackageManager": {}
},
"path": "./generated/schema/"
},
"operations": {
"inSchemaModule": {}
},
"testMocks": {
"none": {}
},
"operationManifest" : {
"path" : "./generated/operationIdentifiers.json",
"version" : "persistedQueries"
}
}
Swift Codegen Setup
let configuration = ApolloCodegenConfiguration(
// Other properties not shown
output: ApolloCodegenConfiguration.FileOutput(
schemaTypes: ApolloCodegenConfiguration.SchemaTypesFileOutput(
path: "./generated/schema/",
moduleType: .swiftPackageManager
)
operations: .inSchemaModule,
testMocks: .none,
operationIdentifiersPath: "./generated/"
)
)

Schema types

output.schemaTypes: SchemaTypesFileOutput

Schema types are common to all generated models and are required for the generated Swift code to compile.

The properties to configure output.schemaTypes are:

Property NameDescription
pathA file path where the generated schema types should be output.

Relative to your project root
moduleTypeHow generated schema types will be linked to your project.

Module type

output.schemaTypes.moduleType: ModuleType

Use the ModuleType value to configure how your schema types are linked to your project. The Code Generation Engine uses this to determine the structure of the generated files, including import statements.

For single target applications, embeddedInTarget(name:) can be used.

For multi-module projects, it is recommended that the schema types be created in a separate module to help with separation of concerns. If using Swift Package Manager, the swiftPackageManager option can help automate module creation.

Note: This option must be set correctly for your project structure or generated code will fail to compile.

The possible values for moduleType are:

ValueDescription
embeddedInTarget(name:accessModifier:)Indicates that you would like to include the generated module directly in your application target.
swiftPackageManagerCreates a schema module as an SPM package that can be included in your project.
otherIndicates that you would like to manually define a schema module using a third party package manager (such as Cocoapods).

Embedded in target

ModuleType.embeddedInTarget(name: String, accessModifier: AccessModifier)

This option indicates that you would like to include the generated module directly in your application target.

The name parameter must specify the name of the target the schema types will be included in. This will be used to generate import statements for generated . Use the accessModifier parameter to control the visibility of the generated code.

No module will be created for the schema types. Instead, generated schema types will be enclosed in a caseless namespace enum.

When creating a single target application, this option allows you to include 's generated module directly in your application target.

Note: When using this module type, you are responsible for ensuring the generated files are linked to your application target.

CLI Configuration JSON
"output": {
"schemaTypes": {
"moduleType": {
"embeddedInTarget": {
"name": "MyApplicationTarget",
"accessModifier": "internal"
}
},
"path": "./generated/schema/"
}
}
Swift Codegen Setup
let configuration = ApolloCodegenConfiguration(
// Other properties not shown
output: ApolloCodegenConfiguration.FileOutput(
schemaTypes: ApolloCodegenConfiguration.SchemaTypesFileOutput(
path: "./generated/schema/",
moduleType: .embeddedInTarget(name: "MyApplicationTarget", accessModifier: .internal)
)
...
)
)

Swift package manager

ModuleType.swiftPackageManager

This option automates the creation of an SPM package for your schema types. This generates a Package.swift file that is suitable for linking the generated schema types files to your project using Swift Package Manager.

The schema types will be contained in a stand-alone module with the schemaNamespace provided. Other targets in your application that contain generated models must have a dependency on this target.

For multi-module projects using Swift Package Manager, this is the recommended configuration option.

Including schema types in your own Package.swift file:

This option generates an SPM package with its own Package.swift file. This is ideal if you want to share your schema module across multiple projects or using Xcode's Package Dependency GUI.

If you would like to include your schema module as a target in your own Package.swift file, you can define a target with the name and path of the generated files in your Package.swift file.

CLI Configuration JSON
"output": {
"schemaTypes": {
"moduleType": {
"swiftPackageManager": {}
},
"path": "./generated/schema/"
}
}
Swift Codegen Setup
let configuration = ApolloCodegenConfiguration(
// Other properties not shown
output: ApolloCodegenConfiguration.FileOutput(
schemaTypes: ApolloCodegenConfiguration.SchemaTypesFileOutput(
path: "./generated/schema/",
moduleType: .swiftPackageManager
)
...
)
)

Other schema module types

ModuleType.other

This value should be used when you would like to define a schema module using another package management system (such as CocoaPods), or you want more control over the generated package than what ModuleType.swiftPackageManager allows, or manually creating your own targets or modules in another way.

ModuleType.other indicates to the Code Generation Engine that your schema types will be contained in their own target, rather than embedded in your application target. This affects the import statements in your generated definition files.

Using this option, you are required to create a target, or module, for your schema module using your preferred package manager.

Note: You must specify the name of the target, or module, you created in the schemaNamespace property of your configuration. This will be used for import statements as well as to fully qualify the referenced types in generated files.

CLI Configuration JSON
"output": {
"schemaTypes": {
"moduleType": {
"other": {}
},
"path": "./generated/schema/"
}
}
Swift Codegen Setup
let configuration = ApolloCodegenConfiguration(
// Other properties not shown
output: ApolloCodegenConfiguration.FileOutput(
schemaTypes: ApolloCodegenConfiguration.SchemaTypesFileOutput(
path: "./generated/schema/",
moduleType: .other
)
...
)
)

Operations

files are generated from all the operation definitions matched by your configuration's operationSearchPaths. Each (, , or ) and definition will be created in a separate file.

To learn more about , check out Defining operations

The output.operations property value determines the location of the generated files:

ValueDescription
inSchemaModuleOperation models will be included in the schema types module.
relative(subpath:accessModifier:)Operation models will be output relative to their defining .graphql files.
absolute(path:accessModifier:)All operation object files will be located in the specified path.

Operations in the schema module

OperationsFileOutput.inSchemaModule

This option includes the generated models in the same module as your schema types.

This means the output location or your models is determined by the output.schemaTypes.path option. When using this option the directory of your schema module will include a Schema folder for your schema types, as well as folders for your operations, fragments, and local cache mutations.

When using this option, generated models are expected to be included in the same target as the schema types. Therefore they will not include import statements to import the schema module.

Relative operations output

OperationsFileOutput.relative(subpath: String?, accessModifier: AccessModifier)

This option outputs your generated models relative to their definition (.graphql files).

Using relative outputs, you have complete control over where your operation definitions are generated. It is common practice to co-locate your operation and models with the parts of your project that will use them.

An optional subpath parameter can be provided to generate models in a subfolder that will be created within the directory of their defining definition file. If no subpath is specified then all files will be generated alongside thier definition files. Use the accessModifier property to control the visibility of the generated code.

Operation Models in a multi-module project:

If your project constists of multiple modules you can use relative output, to generate operation models into directories that are part of different modules in your project. In order to generate relative operation models for a multi-module project, all of your operation models should be generated at the same time. This means the Code Generation Engine should be run in a context that has access to the source files of all of your modules.

After generating your models ensure that:

  • All modules containing generated models are linked to the target containing your schema types.
  • All referenced by your models are either:
    • Included in the same target as the referencing ; or
    • Included in the schema module directly

In the future, we plan to allow you to include fragments in other modules and share them between multiple modules in your project.

Absolute operations output

OperationsFileOutput.absolute(path: String, accessModifier: AccessModifier)

This option outputs all of your generated models in a single directory.

Specify the directory for your models using the path parameter. This is resolved as a relative path from the directory containing your apollo-codegen-config.json file when using the CLI. Use the accessModifier property to control the visibility of the generated code.

Test mocks

output.testMocks: TestMockFileOutput

Test mock objects can be created for your models, to configure whether test mocks are generated and how they are added to your project, use this option.

To learn more about using test mocks to mock your models, see the Test mocks documentation.

The output.testMocks option can be configured with the following values:

ValueDescription
noneTest mocks will not be generated.
swiftPackage(targetName:)Test mock files will be generated and included in a target defined in an SPM package.
absolute(path:accessModifier:)Test mock files will be generated at the specified path.

Test mocks in a Swift Package

TestMockFileOutput.swiftPackage(targetName: String?)

This option generates test mock files and defines a target in the schema modules generated Package.swift file that is suitable for linking the test mock files to your test target using Swift Package Manager.

The name of the test mock target can be specified with the targetName parameter. If no targetName is provided, the target name defaults to "${schemaNamespace}TestMocks".

Note: Using this option requires your output.schemaTypes.moduleType to be .swiftPackageManager. If this option is provided without the .swiftPackageManager module type, code generation will fail.

Absolute test mocks output

TestMockFileOutput.absolute(path: String, accessModifier: AccessModifier)

This option outputs all of your generated test mocks in a single directory.

Specify the directory for your test mocks using the path parameter. This is resolved as a relative path from the directory containing your apollo-codegen-config.json file when using the CLI. Use the accessModifier property to control the visibility of the generated code.

Note:

  • When using this option, you are responsible for ensuring the generated test mocks are linked to your test target.
  • Test mocks generated this way may also be manually embedded in a test utility module that is imported by your test target.
  • Test mocks are required to be in a target or module that is separate from the schema module and will always include import statements linking the schema module.

Output options

The code generation engine supports a number of configuration options to change the behaviour of the generator and tailor the generated Swift code to your specific needs.

The top-level properties are:

Property NameDescription
additionalInflectionRulesAny non-default rules for pluralization or singularization of type names.
deprecatedEnumCasesAnnotate generated Swift enums with the Swift @available attribute for GraphQL enum cases annotated with the built-in @deprecated directive.
schemaDocumentationInclude or exclude schema documentation in the generated files.
selectionSetInitializersGenerate initializers for your generated selection set models.
operationDocumentFormatHow to generate the operation documents for your generated operations. This can be used to generate operation identifiers for use with a server that supports Persisted Queries or Automatic Persisted Queries
cocoapodsCompatibleImportStatementsGenerate import statements that are compatible with including Apollo via Cocoapods.
warningsOnDeprecatedUsageAnnotate generated Swift code with the Swift @available attribute and @deprecated argument for parts of the GraphQL schema annotated with the built-in @deprecated directive.
conversionStrategiesRules for how to convert the names of values from the schema in generated code.
pruneGeneratedFilesWhether unused generated files will be automatically deleted.
markOperationDefinitionsAsFinalWhether generated GraphQL operation and local cache mutation class types will be marked as final.
CLI Configuration JSON
"options": {
"additionalInflectionRules": [{
"pluralization": {
"replacementRegex": "animals",
"singularRegex": "animal"
}
}],
"deprecatedEnumCases": "include",
"schemaDocumentation": "include",
"selectionSetInitializers" : {
"operations": false,
"namedFragments": false,
"localCacheMutations" : true,
"definitionsNamed": [
"MyOperation",
"MyFragment"
]
},
"operationDocumentFormat" : ["definition", "operationId"],
"cocoapodsCompatibleImportStatements": false,
"warningsOnDeprecatedUsage": "include",
"conversionStrategies": {
"enumCases": "camelCase",
"fieldAccessors": "default",
"inputObjects": "camelCase"
},
"pruneGeneratedFiles": true,
"markOperationDefinitionsAsFinal": true
}
Swift Codegen Setup
let configuration = ApolloCodegenConfiguration(
// Other properties not shown
options: ApolloCodegenConfiguration.OutputOptions(
additionalInflectionRules: [
.pluralization(
singularRegex: "animal",
replacementRegex: "animals"
)
],
deprecatedEnumCases: .include,
schemaDocumentation: .include,
selectionSetInitializers: [
.localCacheMutations,
.operation(named: "MyOperation"),
.fragment(named: "MyFragment)
],
operationDocumentFormat: [.document, .operationId],
cocoapodsCompatibleImportStatements: false,
warningsOnDeprecatedUsage: .include,
conversionStrategies: ApolloCodegenConfiguration.ConversionStrategies(
enumCases: .camelCase,
fieldAccessors: .default,
inputObjects: .camelCase
),
pruneGeneratedFiles: true,
markOperationDefinitionsAsFinal: true
)
)

Experimental features

The code generation engine supports some behaviors where the affect on the generated code is considered experimental. An example of this is a specification of the that is not yet formalized and undergoing change as the proposal advances.

Note: These features could change at any time and are not guaranteed to always be available.

The current supported experimental features are:

Valueescription
clientControlledNullabilityIf enabled, codegen will understand and parse Client Controlled Nullability. Read the RFC for more detail.
legacySafelistingCompatibleOperationsIf enabled, the generated operations will be transformed using a method that attempts to maintain compatibility with the legacy behavior from apollo-tooling for registering persisted operation to a safelist.

Note: Safelisting queries is a deprecated feature of Apollo Server that has reduced support for legacy use cases. This option may not work as intended in all situations.
CLI Configuration JSON
"experimentalFeatures": {
"clientControlledNullability": false,
"legacySafelistingCompatibleOperations": false
}
Swift Codegen Setup
let configuration = ApolloCodegenConfiguration(
// Other properties not shown
experimentalFeatures: ApolloCodegenConfiguration.ExperimentalFeatures(
clientControlledNullability: false,
legacySafelistingCompatibleOperations: false
)
)

Schema download configuration

An optional step in the code generation process is to fetch a from a remote server. This step ensures that you always have an up-to-date schema on which to base your and it eliminates the need to manually download the schema outside of the automated process.

The properties to configure the schema download are:

Property NameDescription
downloadMethodHow to download the schema.
downloadTimeoutThe maximum time (in seconds) to wait before indicating that the download timed out.
headersAny additional headers to include when retrieving your schema. This is useful when the schema download requires authentication.
outputPathThe local path where the downloaded schema should be written to.

Download method

There are two supported sources for fetching a :

1. Apollo server registry

The Apollo schema registry serves as a central hub for managing your .

The properties you will need to configure are:

Property NameDescription
apiKeyAPI key to use when retrieving your schema from the Apollo Registry.
graphIDIdentifier of the graph to fetch. Can be found in Apollo Studio.
variantVariant of the graph in the registry.
CLI Configuration JSON
"schemaDownload": {
"downloadMethod": {
"apolloRegistry": {
"_0": {
"graphID": "your-graphid",
"apiKey": "your-api-key",
"variant": "current"
}
}
},
"downloadTimeout": 60,
"headers": {
"Accept-Encoding" : "gzip",
"Authorization" : "Bearer <token>"
},
"outputPath": "./graphql/"
}
Swift Codegen Setup
let configuration = ApolloCodegenConfiguration(
// Other properties not shown
schemaDownload: ApolloSchemaDownloadConfiguration(
using: .apolloRegistry(.init(
apiKey: "your-api-key",
graphID: "your-graphid",
variant: "current")),
timeout: 60.0,
headers: [
.init(key: "Accept-Encoding", value: "gzip"),
.init(key: "Authorization", value: "Bearer <token>")
],
outputPath: "./graphql/")
)

2. GraphQL introspection

A service supports over its schema.

Note: Many production servers disable for security reasons. If your introspection is failing check that it is not disabled.

The properties you will need to configure are:

Property NameDescription
endpointURLURL of the GraphQL introspection service.
httpMethodHTTP request method.
outputFormatOutput format for the downloaded schema.
includeDeprecatedInputValuesSpecify whether input values annotated with the built-in @deprecated directive should be included in the fetched schema.
CLI Configuration JSON
"schemaDownload": {
"downloadMethod": {
"introspection": {
"endpointURL": "https://server.com",
"httpMethod": {
"POST": {}
},
"includeDeprecatedInputValues": false,
"outputFormat": "SDL"
}
},
"downloadTimeout": 60,
"headers": [],
"outputPath": "./graphql/"
}
Swift Codegen Setup
let configuration = ApolloCodegenConfiguration(
// Other properties not shown
schemaDownload: ApolloSchemaDownloadConfiguration(
using: .introspection(
endpointURL: URL(string: "https://server.com")!),
timeout: 60.0,
headers: [],
outputPath: "./graphql/")
)

For more details, see the section on downloading a schema.

Operation Manifest Configuration

Optional settings used to configure generation of the identifier manifest for use with Persisted Queries.

Property NameDescription
pathLocal path where the generated operation manifest file should be written.
versionThe version format to use when generating the operation manifest.
generateManifestOnCodeGenerationWhether or not the operation manifest should be generated every time code generation is run. Defaults to false.
CLI Configuration JSON
"operationManifest" : {
"generateManifestOnCodeGeneration" : false,
"path" : "/operation/identifiers/path",
"version" : "persistedQueries"
}
Swift Codegen Setup
let configuration = ApolloCodegenConfiguration(
// Other properties not shown
operationManifest: .init(
path: "./manifest/operationManifest.json",
version: .persistedQueries,
generateManifestOnCodeGeneration: false
)
)

Full Codegen Configuration Example

Below is an example that illustrates an apollo-codegen-config.json where every available option is configured in some way to show its usage and formatting:

apollo-codegen-config.json
{
"schemaNamespace" : "MySchema",
"schemaDownload": {
"downloadMethod": {
"introspection": {
"endpointURL": "https://server.com",
"httpMethod": {
"POST": {}
},
"includeDeprecatedInputValues": false,
"outputFormat": "SDL"
}
},
"downloadTimeout": 60,
"headers": [],
"outputPath": "./graphql/"
},
"experimentalFeatures" : {
"clientControlledNullability" : true,
"legacySafelistingCompatibleOperations" : true
},
"operationManifest" : {
"generateManifestOnCodeGeneration" : false,
"path" : "/operation/identifiers/path",
"version" : "persistedQueries"
},
"input" : {
"operationSearchPaths" : [
"/search/path/**/*.graphql"
],
"schemaSearchPaths" : [
"/path/to/schema.graphqls"
]
},
"output" : {
"operations" : {
"absolute" : {
"accessModifier" : "internal",
"path" : "/absolute/path"
}
},
"schemaTypes" : {
"moduleType" : {
"embeddedInTarget" : {
"accessModifier" : "public",
"name" : "SomeTarget"
}
},
"path" : "/output/path"
},
"testMocks" : {
"swiftPackage" : {
"targetName" : "SchemaTestMocks"
}
}
},
"options" : {
"additionalInflectionRules" : [
{
"pluralization" : {
"replacementRegex" : "animals",
"singularRegex" : "animal"
}
}
],
"cocoapodsCompatibleImportStatements" : true,
"conversionStrategies" : {
"enumCases" : "none",
"fieldAccessors" : "camelCase",
"inputObjects": "camelCase"
},
"deprecatedEnumCases" : "exclude",
"operationDocumentFormat" : [
"definition"
],
"pruneGeneratedFiles" : false,
"schemaDocumentation" : "exclude",
"selectionSetInitializers" : {
"localCacheMutations" : true
},
"warningsOnDeprecatedUsage" : "exclude"
}
}
Previous
The Codegen CLI
Next
Downloading a Schema
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company