Graphql-ruby: Documentation is a mess .graphql??? .rb??? app/graphql/post_type.rb??? app/graphql/types/post_type???

[ch-tactica]

The documentation for this library seems to be a bit chaotic at the moment, it's extremely difficult to discern how exactly I'm supposed to be using this library.

To start, the rails generator places all types in the app/graphql/types folder with a .rb extension. OK, makes sense. Now when I go to read the documentation to find the next steps, what do I find?

http://graphql-ruby.org/getting_started:

Types describe objects in your application and form the basis for GraphQL’s type system.

# app/graphql/post_type.graphql
class PostType < GraphQL::Schema::Object
  description "A blog post"
  field :id, ID, null: false
  field :title, String, null: false
  # fields should be queried in camel-case (this will be `truncatedPreview`)
  field :truncated_preview, String, null: false
  # Fields can return lists of other objects:
  field :comments, [CommentType], null: true,
    # And fields can have their own descriptions:
    description: "This post's comments, or null if this post has comments disabled."
end

What?? Not only do the getting started docs have a completely different file extension .graphql, but the post_type is sitting in a different folder, and inherits from a different class?

"Alright, I'll simply disregard the getting started guide, perhaps it's out of date" I thought. So I go to the Object type docs, thinking surely that would be the source of truth for how I'm supposed to use my new object type that the rails generator created for me..... think again!

http://graphql-ruby.org/type_definitions/objects.html

class User < GraphQL::Schema::Object
  field :email, String, null: true
  field :handle, String, null: false
  field :friends, [User], null: false
end

Wait, so do we need the Type suffix in the class name? How is it avoiding name collisions with the underlying User model!?

What's going on here? I have absolutely zero sense of what conventions are meant to be used for this library -- there seems to be red hearings all over the place and the documentation contradicts what's in the rails generators.

[swalkinshaw]

Yeah some of those pages are definitely out of date. They should all be consistent with what the generator generates I'd think. The landing page has the correct example:

# app/graphql/types/profile_type.rb class Types::ProfileType < Types::BaseObject field :id, ID, null: false field :name, String, null: false field :avatar, Types::PhotoType, null: true end

Types should be in the types subdirectory and be under the Types namespace.

[gadimbaylisahil]

Agree, improving documentation would be much appreciated! It's hard to navigate

[jturkel]

My team has been confused by this too. I'd be happy to take a pass over the doc and make it consistent. If we go with the Type name suffix for object types, should we follow a similar scheme for input objects, unions, interfaces, scalars and enums? Looks like the gem handles this properly during type generation but I couldn't find any examples in the doc or generators leveraging this.

[rmosolgo]

Thanks for reporting this issue with the docs, I've revisited the path names in 8403452f2 and also added the missing Types:: prefixes to the examples. Personally, I'm torn about the *Type suffix. It's helpful for avoiding naming conflicts, but it's also ugly. I can't decide 😖 Happy to work out some answer in another issue!

[dan-kenny]

I am modelling hotels and having a RoomTypeType is very jarring.

We just discovered the enforcing of the Type suffix and it was really unexpected.

I'd prefer it not to be there and deal with naming collisions myself.

[ch-tactica]

I think a suffix is a good idea, how else would you avoid naming conflicts with models? Just be consistent. I don't think "Type" is a verry good suffix either. What's the convention used in GraphQL?

[swalkinshaw]

@dank00 you can use RoomType as the class name then override the generated type name:

class RoomType < GraphQL::Schema::Object
  graphql_name 'RoomType'
end

But agreed it's confusing when you first run into it.

[dan-kenny]

ah thanks @swalkinshaw unfortunately, I also have a Room 😩

so my directory structure would be:

hotel_type.rb
room_type.rb
room???.rb

[dan-kenny]

I think a suffix is a good idea, how else would you avoid naming conflicts with models? Just be consistent. I don't think "Type" is a verry good suffix either. What's the convention used in GraphQL?

types and inputs are just named according to the domain, an implementer of the spec shouldn't take it any further.

[swalkinshaw]

how else would you avoid naming conflicts with models?

They can be within a module such as Types:: which the docs has anyway. The Type suffix isn't really necessary at that point. Yes you'll need to fully qualify constants sometimes for conflicts with models, but I'm not sure this gem should worry about that.