Vishesh Duggar bio photo

Vishesh Duggar

CTO Software @vamstar. 15 years in tech. Entrepreneurial with a keen interest in product development and usability. Interested in working on high impact ideas.

Subscribe to my mailing list

Can I help with tech or strategy?

Contact on LinkedIn

Vamstar LinkedIn Twitter Github

To generate documentation for the GraphQL api the schema needs to have comments or description. Here is an example of how you could add a comment.


"""
Location information for an actor
"""
type ActorLocation {
  """
  City
  """
  city: String

  """
  Country name
  """
  country: String

  """
  Country code
  """
  countryCode: String

  """
  Region name
  """
  region: String

  """
  Region or state code
  """
  regionCode: String
}


TypeGraphQL exposes the description attribute to inject comments into the generated schema.


@ObjectType({ description: "The recipe model" })
class Recipe {
  @Field(type => ID)
  id: string;

  @Field({ description: "The title of the recipe" })
  title: string;

  @Field(type => [Rate])
  ratings: Rate[];

  @Field({ nullable: true })
  averageRating?: number;
}

You could use GraphQL Playground to host a live version of your api docs for GraphQL but it helps to have a static version incase you don’t want people hitting the api unless they don’t really have an account.

To generate the docs you would need to feed the schema to (Docusaurus)[https://docusaurus.io/docs].If you are using type-graphql to generate static docs is to first emit the GraphQL schema https://typegraphql.com/docs/emit-schema.html#docsNav.

  1. Scaffold a simple docusaurus

    npx @docusaurus/init@latest init generate-gql-docs classic

  2. Install generator

    npm install –save @edno/docusaurus2-graphql-doc-generator

  3. Change config in docusaurus.config.js to point to the GraphQL Schema
    plugins: [
    [
      require.resolve('@edno/docusaurus2-graphql-doc-generator'),
      {
        schema: './schema.gql',
        rootPath: './docs', // docs will be generated under './docs/swapi' (rootPath/baseURL)
        baseURL: 'api',
        linkRoot: '/docs',
      },
    ],
  ],
  1. Generate docs

    npx docusaurus graphql-to-doc

  2. To see it in action

    npm run start

Code for this is here https://github.com/visheshd/generate-gql-docs

Close to 15 years in tech; I've served as a CTO and advisor to multiple organizations. Brought close to 20 products to market. As a founding member of multiple organizations I've done everything from tech to stratgey, sales, marketing, hiring, accounting and more. Experience in a variety of technologies including but not limited to AWS, Node, React, Serverless, ElasticSearch, Groovy, Java, Typescript, Angular, Grails, PHP, Drupal, Wordpress.

Always interested in looking at new tech, strategy and ways I can add value to organizations.

Contact Me.