Great post, thank you. There's a question many people ask, although it's not that easy to find answers for:
How can we (if we can) document the GraphQL schema (fields, queries, mutations) using code first approach?
I use code first, but I also want "DOCS" be more meaningful in the playground. If you know it and you can demo it in your examples, that'd be insanely awesome.
you can add a description option to the code first decorators @Query, @Mutation, @ObjectType, @Field and more.
Here is an example how to add a description:
@ObjectType({description:'Authentication Payload'})exportclassAuth{@Field({description:'JWT Bearer Token for Authentication'})token:string;....}
This documentation is added to the generated graphql schema as comment """DESCRIPTION""" to the field or query, this is getting picked up by the graphql playground.
The recipe seems to work, just tried it in NestJS 7. Apollo's GraphQL Playground doesn't make descriptions quite visible though. But they are there (the "DOCS" tab).
The set of supported markups is yet to be discovered. Markdown's code seems to work, don't know about the rest.
Hey Marc,
Great post, thank you. There's a question many people ask, although it's not that easy to find answers for:
How can we (if we can) document the GraphQL schema (fields, queries, mutations) using code first approach?
I use code first, but I also want "DOCS" be more meaningful in the playground. If you know it and you can demo it in your examples, that'd be insanely awesome.
Cheers,
Alex
Hi Alex,
you can add a
descriptionoption to the code first decorators@Query,@Mutation,@ObjectType,@Fieldand more.Here is an example how to add a description:
This documentation is added to the generated graphql schema as comment
"""DESCRIPTION"""to the field or query, this is getting picked up by the graphql playground.Let me know if this helps you.
Hey Marc,
Thank you for the info.
The recipe seems to work, just tried it in NestJS 7. Apollo's GraphQL Playground doesn't make descriptions quite visible though. But they are there (the "DOCS" tab).
The set of supported markups is yet to be discovered. Markdown's
codeseems to work, don't know about the rest.Cheers!
Good idea to add markdown to the docs that helps too.
I am glad I could help :)