Schema support

[pepicrft]

Context

One of the things that struck me when playing with React and GraphQL APIs is this concept of generating Typescript models off a GraphQL schema and queries. It's an amazing developer experience because you don't have to write and maintain the code that models the endpoints and the models returned by them. Here is an example of one of those tools.

What

I think having that experience built into Tuist would be amazing. I've been thinking about this for a few days and this is the API I came up with.

Schemas.swift

I think we could introduce a new manifest type located at Tuist/Schemas.swift. The structure would be something similar to this:

import ProjectDescription

let schemas = Schemas([
  "my_graphql_api": .graphql(url: "https://tuist.io/graphq"),
  "my_rest_api": .openAPI(url: "https://tuist.io/path/to/spec")
])

Command to update the schema

Tuist would expose a new command, tuist schema update, that would pull the latest version of the schemas and store them locally under Tuist/Schemas:

Tuist/
  Schemas/
     my_graphql_api.schema
     my_rest_api.schema

New target dependency type

In order for developers to specify that they'd like their targets to have access to the models generated off the schema, we could introduce a new target dependency:

let target = Target(dependencies: [.schema("my_graphql_api", linking: .static)])

A mapper would use either SwaGen or Syrup to generate the Swift models, create a new target containing the generated Swift files, and add the target as a dependency of the targets that reference it. Then developers should be able to import the models by doing:

import MyGraphqApiSchema
import MyRestApiSchema

[kikeenrique]

Having a custom framework autogenerated from a api schema sounds quite nice.
Maybe the word Schema could be a bit confusing with Xcode schemes?

[pepicrft]

Ouch, that's a good point. How would you call it instead? Here are some ideas: APISchemes, APISpecifications, NetworkSchemes..

[kikeenrique]

Maybe ApiSchema.
I think this makes it quite easy to understand even the first time you read a file with this definitions.

import ProjectDescription

let apiSchemas = ApiSchema([
  "my_graphql": .graphql(url: "https://tuist.io/graphq"),
  "my_rest": .openAPI(url: "https://tuist.io/path/to/spec")
])

Tuist/
  ApiSchema/
     my_graphql.schema
     my_rest.schema

let target = Target(dependencies: [.apischema("my_graphql", linking: .static)])

I would suggest another small detail in naming imports.

import ApiSchemaMyGraphql
import ApiSchemaMyRest

instead of

import MyGraphqlApiSchema
import MyRestApiSchema

Even though I think this is more a "what color do you like?" preference.

Opinions?

[pepicrft]

I really like naming it ApiSchema. As you said, regarding the name is a matter of taste, I don't have strong opinions in regards to the ApiSchema being a suffix or a prefix.

[fortmarek]

This is something a lot of teams do already, so it makes sense for me to add this to tuist. At our company we use GRPC, which doesn't use schemas though, but protocol buffers - so schema naming would not work for this case, I wonder if there are more API-related generated code we would want to support in the future (it'd be great to assess the possible future needs before deciding upon some API)

I have also one question if it is necessary to add a new manifest for this? The discoverability of a new manifest is basically only from the documentation, so from that point-of-view it'd be better in Project.

But otherwise, i think a lot of people would find this helpful!

[kikeenrique]

As a matter of fact, when I read about this proposal, I immediately thought in plugins.