Get started with Apollo iOS codegen

This short tutorial guides you through the basic concepts of generating Swift code with Apollo iOS. We'll introduce you the core capabilities of code generation, and walk through the process of generating Swift code using a GraphQL schema and GraphQL operations.

For more in-depth details, see Code generation.

Step 1: Project Setup

Start by creating a new directory, and navigating into it:

1
mkdir ios-code-gen-example
2
cd ios-code-gen-example

Step 2: Download a GraphQL schema

We'll use the StarWars GraphQL API for this example. You can check this schema out using Apollo Studio.

Where to download a schema from Apollo Studio

On the right-hand side in Apollo Studio find the drop-down to download the schema, shown in the above screenshot. Apollo Studio supports both JSON or Raw formats. For this tutorial select Raw which downloads the GraphQL schema in the Schema Definition Language (SDL) format.

Clicking Raw will download a file named star-wars-swapi@current.graphql.

Step 3: Move the downloaded schema into your project

Download or move the already downloaded star-wars-swapi@current.graphql file into the directory you created in Step 1.

Rename the file extension from .graphql to .graphqls. Note the s on the end signifying a GraphQL schema file.

Step 4: Create a GraphQL operation

You'll also need to create a GraphQL operation file because the code generation engine requires both a schema and at least one operation to generate code.

We'll be using the allFilms Query operation as an example. Clicking this link will open Explorer in Apollo Studio where you can select the fields you would like to be fetched. Alternatively, the query text below already has fields selected.

Copy the query text and create a new file named AllFilmsQuery.graphql in the directory you created in Step 1. Paste this query into the new file.

1
query Query {
2
  allFilms {
3
    films {
4
      title
5
      director
6
      releaseDate
7
      speciesConnection {
8
        species {
9
          name
10
          classification
11
          homeworld {
12
            name
13
          }
14
        }
15
      }
16
    }
17
  }
18
}

Step 5: Download the CLI

Browse to the list of Apollo iOS releases in GitHub and find the latest release. In the Assets list for each release will be a pre-built CLI binary called apollo-ios-cli.tar.gz

Download and unzip this file then move the apollo-ios-cli binary file into the directory you created in Step 1.

For more information on the different ways to install the CLI, see the codegen CLI documentation.

Step 6: Create a codegen configuration

Run the following command:

1
./apollo-ios-cli init --schema-namespace StarWarsAPI --module-type swiftPackageManager

The CLI will create a configuration file named apollo-codegen-configuration.json, pre-filled with default values. The file should look similar to this:

1
{
2
  "schemaNamespace": "StarWarsAPI",
3
  "input": {
4
    "operationSearchPaths": ["**/*.graphql"],
5
    "schemaSearchPaths": ["**/*.graphqls"]
6
  },
7
  "output": {
8
    "testMocks": {
9
      "none": {}
10
    },
11
    "schemaTypes": {
12
      "path": "./StarWarsAPI",
13
      "moduleType": {
14
        "swiftPackageManager": {}
15
      }
16
    },
17
    "operations": {
18
      "inSchemaModule": {}
19
    }
20
  }
21
}

Step 7: Generate code

Now you are ready to generate some code! Run the following command:

1
./apollo-ios-cli generate

You should see a new file created at StarWarsAPI/Sources/Operations/Queries/Query.graphql.swift, that looks similar to this:

1
// @generated
2
// This file was automatically generated and should not be edited.
3

4
@_exported import ApolloAPI
5
import StarWarsAPI
6

7
public class Query: GraphQLQuery {
8
  public static let operationName: String = "Query"
9
  public static let document: DocumentType = .notPersisted(
10
    definition: .init(
11
      """
12
      query Query {
13
        allFilms {
14
          __typename
15
          films {
16
            __typename
17
            title
18
            director
19
            releaseDate
20
            speciesConnection {
21
              __typename
22
              species {
23
                __typename
24
                name
25
                classification
26
                homeworld {
27
                  __typename
28
                  name
29
                }
30
              }
31
            }
32
          }
33
        }
34
      }
35
      """
36
    ))
37

38
  public init() {}
39

40
  public struct Data: StarWarsAPI.SelectionSet {
41
    public let __data: DataDict
42
    public init(data: DataDict) { __data = data }
43

44
    public static var __parentType: ParentType { StarWarsAPI.Objects.Root }
45
    public static var __selections: [Selection] { [
46
      .field("allFilms", AllFilms?.self),
47
    ] }
48

49
    public var allFilms: AllFilms? { __data["allFilms"] }
50

51
    /// AllFilms
52
    ///
53
    /// Parent Type: `FilmsConnection`
54
    public struct AllFilms: StarWarsAPI.SelectionSet {
55
      public let __data: DataDict
56
      public init(data: DataDict) { __data = data }
57

58
      public static var __parentType: ParentType { StarWarsAPI.Objects.FilmsConnection }
59
      public static var __selections: [Selection] { [
60
        .field("films", [Film?]?.self),
61
      ] }
62

63
      /// A list of all of the objects returned in the connection. This is a convenience
64
      /// field provided for quickly exploring the API; rather than querying for
65
      /// "{ edges { node } }" when no edge data is needed, this field can be be used
66
      /// instead. Note that when clients like Relay need to fetch the "cursor" field on
67
      /// the edge to enable efficient pagination, this shortcut cannot be used, and the
68
      /// full "{ edges { node } }" version should be used instead.
69
      public var films: [Film?]? { __data["films"] }
70

71
      /// AllFilms.Film
72
      ///
73
      /// Parent Type: `Film`
74
      public struct Film: StarWarsAPI.SelectionSet {
75
        public let __data: DataDict
76
        public init(data: DataDict) { __data = data }
77

78
        public static var __parentType: ParentType { StarWarsAPI.Objects.Film }
79
        public static var __selections: [Selection] { [
80
          .field("title", String?.self),
81
          .field("director", String?.self),
82
          .field("releaseDate", String?.self),
83
          .field("speciesConnection", SpeciesConnection?.self),
84
        ] }
85

86
        /// The title of this film.
87
        public var title: String? { __data["title"] }
88
        /// The name of the director of this film.
89
        public var director: String? { __data["director"] }
90
        /// The ISO 8601 date format of film release at original creator country.
91
        public var releaseDate: String? { __data["releaseDate"] }
92
        public var speciesConnection: SpeciesConnection? { __data["speciesConnection"] }
93

94
        /// AllFilms.Film.SpeciesConnection
95
        ///
96
        /// Parent Type: `FilmSpeciesConnection`
97
        public struct SpeciesConnection: StarWarsAPI.SelectionSet {
98
          public let __data: DataDict
99
          public init(data: DataDict) { __data = data }
100

101
          public static var __parentType: ParentType { StarWarsAPI.Objects.FilmSpeciesConnection }
102
          public static var __selections: [Selection] { [
103
            .field("species", [Specy?]?.self),
104
          ] }
105

106
          /// A list of all of the objects returned in the connection. This is a convenience
107
          /// field provided for quickly exploring the API; rather than querying for
108
          /// "{ edges { node } }" when no edge data is needed, this field can be be used
109
          /// instead. Note that when clients like Relay need to fetch the "cursor" field on
110
          /// the edge to enable efficient pagination, this shortcut cannot be used, and the
111
          /// full "{ edges { node } }" version should be used instead.
112
          public var species: [Specy?]? { __data["species"] }
113

114
          /// AllFilms.Film.SpeciesConnection.Specy
115
          ///
116
          /// Parent Type: `Species`
117
          public struct Specy: StarWarsAPI.SelectionSet {
118
            public let __data: DataDict
119
            public init(data: DataDict) { __data = data }
120

121
            public static var __parentType: ParentType { StarWarsAPI.Objects.Species }
122
            public static var __selections: [Selection] { [
123
              .field("name", String?.self),
124
              .field("classification", String?.self),
125
              .field("homeworld", Homeworld?.self),
126
            ] }
127

128
            /// The name of this species.
129
            public var name: String? { __data["name"] }
130
            /// The classification of this species, such as "mammal" or "reptile".
131
            public var classification: String? { __data["classification"] }
132
            /// A planet that this species originates from.
133
            public var homeworld: Homeworld? { __data["homeworld"] }
134

135
            /// AllFilms.Film.SpeciesConnection.Specy.Homeworld
136
            ///
137
            /// Parent Type: `Planet`
138
            public struct Homeworld: StarWarsAPI.SelectionSet {
139
              public let __data: DataDict
140
              public init(data: DataDict) { __data = data }
141

142
              public static var __parentType: ParentType { StarWarsAPI.Objects.Planet }
143
              public static var __selections: [Selection] { [
144
                .field("name", String?.self),
145
              ] }
146

147
              /// The name of this planet.
148
              public var name: String? { __data["name"] }
149
            }
150
          }
151
        }
152
      }
153
    }
154
  }
155
}

And that's it! You can also review all the additional generated files to get a deeper understanding of how code generation works using the Apollo iOS client.

v1.7

Introduction