Join us for GraphQL Summit, October 10-12 in San Diego. Use promo code ODYSSEY for $400 off your pass.
Launch GraphOS Studio

Code generation

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

Each generated 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 -specific, they include properties only for the GraphQL s included in their corresponding . This means you can rely on the Swift type checker to flag data access errors at compile time.

Check out our step-by-step tutorial on how to get started with Apollo iOS code generation.

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 s you can query on those types. The can be thought of as a contract of what it's possible to ask for.

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

Apollo iOS provides tools to help you obtain your GraphQL . See Downloading a schema for more details.

  1. A set of GraphQL operations and fragments

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

Your input sources can also include files that define GraphQL fragments. These s can be referenced by your 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.

For more information on GraphQL definitions see Defining operations.

All of the GraphQL files that you specify as input sources will be merged into a single GraphQL document. s 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 with your 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 and s 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 s, 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 , our code generator won't know if your operations are valid or what types any of the s 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.

To learn more about running code generation from Swift code, check out Running codegen in Swift code.

13. Write your first subscription
The Codegen CLI
Edit on GitHubEditForumsDiscord