Is it possible to set a description for a field of a type?

[ErtugrulSener]

I know that there is @GraphQLInputField to set the description on input fields (which doesn't work btw. but that's another issue). We can use the annotation on fields also, like:

@Data
@AllArgsConstructor
@NoArgsConstructor
@GraphQLType(name = "Cat")
public class Cat {
    @GraphQLInputField(description = "this is a cool description, but not printed in schema :(", name = "changed_name")
    @GraphQLNonNull private String name;
}

This results in (I am using it as an input and return type in my API):

type Cat {
 name: String!
}

input CatInput {
  changed_name: String!
}

Is there any way for me to set a description on the field of the type, something like @GraphQLField? What I need is the following:

type Cat {
 "this is a desciption for the cats name"
 name: String!
}

I don't need to change the input field.

[ErtugrulSener]

Oh.. is this a duplicate of https://github.com/leangen/graphql-spqr/issues/224?

I think what works is:

@GraphQLQuery(description='this is a cool description')

... but to be honest: this is not obvious.

I would do the following thing:

• use @GraphQLArgument for arguments of querys / mutations
• use @GraphQLInputField for input fields in graphql schema
• use new annotation @GraphQLTypeField for type fields in graphql schema
  • remove the logic for @GraphQLQuery on fields

Did I forgot something?

[kaqqao]

This has been suggested before, but the reason I decided not to do anything about is straight forward: all fields are queries and all queries are fields. There is nothing special about top-level fields/queries in GraphQL. They are merely fields of the root types (that are themselves just regular types). And this isn't only an implementation detail, but a rather important aspect of GraphQL's design that I believe should not be obscured behind Java-specific, or worse yet SPQR-specific terminology. In other words: I want the users to think in GraphQL terms, and not Java terms, as it is the GraphQL schema you're designing, after all. Java is merely the language we use instead of SDL :)

[kaqqao]

And yes, you got it right — you can place @GraphQLQuery to any output field anywhere :)

[ErtugrulSener]

This has been suggested before, but the reason I decided not to do anything about is straight forward: all fields are queries and all queries are fields. There is nothing special about top-level fields/queries in GraphQL. They are merely fields of the root types (that are themselves just regular types). And this isn't only an implementation detail, but a rather important aspect of GraphQL's design that I believe should not be obscured behind Java-specific, or worse yet SPQR-specific terminology. In other words: I want the users to think in GraphQL terms, and not Java terms, as it is the GraphQL schema you're designing, after all. Java is merely the language we use instead of SDL :)

Okay, I agree with that and I understand the reasoning behind your decision of naming. But something like that should be in a rich documentation about the "framework" SPQR.

Is there any plan on going for a documentation like DGS has? https://netflix.github.io/dgs/getting-started/ Or spring graphql? https://docs.spring.io/spring-graphql/docs/current/reference/html/

If not, is it time to start writing some? I would start with really basic use cases and you could go along with the more advanced stuff, if you like to. Maybe you could bootstrap a project for that and care about the "integration" to refer to it on the README's and we could contribute to it.

[kaqqao]

To be honest, any help with documentation would be the best contribution this project could receive. If you decide to write anything, I'll publish it on GitHub pages...

[kaqqao]

I'll close this issue and open a new one as the discussion has now gone in a different direction.