Code generation

Apollo iOS generates operation objects for your GraphQL operations, providing a type-safe way to construct operations and provide values for input variables in your Swift code.

Each generated operation contains a set of robust, strongly-typed models for its response. These generated models help you access your GraphQL response data in a type-safe and flexible format. You don't need to deal with parsing JSON responses or passing around dictionaries of values that require manual casting. You also don't need to write model types yourself, because models are generated from the GraphQL operations you define.

Because generated response models are operation-specific, they include properties only for the GraphQL fields included in their corresponding operation. This means you can rely on the Swift type checker to flag data access errors at compile time.

GraphQL source files

To generate models, Apollo iOS requires two input sources:

1. A GraphQL schema

The GraphQL schema is a list of all of the types that are available and the fields you can query on those types. The schema can be thought of as a contract of what it's possible to ask for.

A schema is provided by every GraphQL server. You can generally get your schema from your server via an introspection query or from Apollo Studio.

2. A set of GraphQL operations and fragments

A GraphQL operation defines an interaction with your schema. A GraphQL operation can be a query, a mutation, or a subscription. All operations define a set of fields from the types in your schema to fetch data for. The operation definition determines what the response your GraphQL server provides will include.

Your operation input sources can also include files that define GraphQL fragments. These fragments can be referenced by your operation definitions.

In order for Apollo to generate useful models, you must define at least one operation. This tells us what data you would like to fetch.

All of the GraphQL operation files that you specify as input sources will be merged into a single GraphQL document. Fragments defined in one file are available across all operation input sources. This means operation and fragment names must be unique across all input sources.

Apollo iOS combines the type information from your schema with your operation definitions to generate models. The schema provides the information needed to generate type-safe models, and your operations define the shape and structure of the generated models.

The Apollo iOS Code Generation Engine parses your schema and operations and ensures that your operations are valid to be performed against the schema provided. It generates models that include all of the necessary information to create type-safe operations, send those operations as network requests, and parse the response data onto the type-safe response models.

There are many choices to be made about the shape of the generated models and how they are packaged to be used in your project. You specify this through a code generation configuration.

The most basic way to think about these is with the following equation:

Schema + Operations + Configuration = Code

If you don't have any operations, our code generator won't know what information you want to fetch, so it can't generate the code to send a request or parse a result. If you don't provide a schema, our code generator won't know if your operations are valid or what types any of the fields you want to fetch will return, so it can't generate type-safe models. If you don't provide a configuration our code generator can only make general assumptions about the generated code which may not be the best choice for your needs. If you have all three, the appropriate checks can be made and type-safe code can be generated, in a precise way for your project.

Running code generation

The Apollo code generation engine can be run using one of two methods:

The Codegen CLI

This is the recommended method for most use cases.

The Codegen CLI is the simplest way to get started with Apollo iOS. The correct version of the CLI is automatically bundled with our SPM and Cocoapod packages, so you never have to worry about installation or updates.

Swift Scripting

For advanced use cases, you can include our code generation engine within your own Swift project.