Auto-generate GraphQL comments in SDL to support a self-documenting API

[dthyresson]

I've wanted to support comments in SDL to help auto-generate a self-documenting GraphQL api for awhile.

It helps document in both the GraphiQL Playground, but also can be used by Docusaurus plug-ins to generate publishable docs. See: https://github.com/graphql-markdown/graphql-markdown

This PR adds comments to

• SDL generators
• root schema

with default comments and descriptions to help self-document the GraphQL API.

What are comments and descriptions?

See: graphql/graphql-spec#420

This can add comments in GraphiQL for:

• redwood root schema and queries
• queries
• mutations
• type/objects
• input types for create and update
• enums

For example:

Prisma Comments

Per @orta 's suggestion, the description now defaults to the Prisma documentation comment if present.

For example:

model WorldCity {
  /// The underlaying ID
  id           String   @id @default(uuid())
  /// Created at timestamp
  createdAt    DateTime @default(now())
  /// Created at timestamp
  updatedAt    DateTime @updatedAt
  /// The id in the SimpleMaps service
  simpleMapsId BigInt   @unique
  /// The name of a city
  city         String
  /// The name of a city in ASCII
  cityAscii    String
  /// Geocordinates of a city, latitude
  lat          Float
  /// Geocordinates of a city, longitude
  lng          Float
  /// Country in which the city is located
  country      String
...

Can default to ...

"""Representation of WorldCity."""
type WorldCity {
  """
  WeatherReport
  
  Description for WeatherReport.
  """
  WeatherReport: [WeatherReport]!

  """
  adminName
  
  Description for adminName.
  """
  adminName: String

  """
  capital
  
  Description for capital.
  """
  capital: String

  """
  city
  
  The name of a city
  """
  city: String!

  """
  cityAscii
  
  The name of a city in ASCII
  """
  cityAscii: String!

  """
  country
  
  Country in which the city is located
  """
  country: String!

  """
  createdAt
  
  Created at timestamp
  """
  createdAt: DateTime!

  """
  id
  
  The underlaying ID
  """
  id: String!

  """
  iso2
  
  Description for iso2.
  """
  iso2: String!

  """
  iso3
  
  Description for iso3.
  """
  iso3: String!

  """
  lat
  
  Geocordinates of a city, latitude
  """
  lat: Float!

  """
  lng
  
  Geocordinates of a city, longitude
  """
  lng: Float!

  """
  population
  
  Description for population.
  """
  population: Int

  """
  simpleMapsId
  
  The id in the SimpleMaps service
  """
  simpleMapsId: BigInt!

  """
  updatedAt
  
  Updated at timestamp
  """
  updatedAt: DateTime!
}

ToDo

• Support enum model name documentation
• Document how to use comments on Prisma schema to self-document GraphQL API
• Demo Docusaurus plugin and document setup with screenshots.

Note:

I did consider added a generator option to include or exclude comment generation, but thought including comments is a better practice.

But, if others think they should be on be default with an option to run off (or vice versa) I can see that, too.

[netlify]

✅ Deploy Preview for redwoodjs-docs ready!

Name	Link
🔨 Latest commit	2cde232
🔍 Latest deploy log	https://app.netlify.com/sites/redwoodjs-docs/deploys/62ec00648250b000087dc236
😎 Deploy Preview	https://deploy-preview-5824--redwoodjs-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[orta]

Nice work, I fully describe my prisma models with /// which also propogates into JSDocs, you might to have the generators bring them from the prisma file also

model Game {
  /// The underlaying ID
  id String @id @unique

  /// The pretty url reference for the game
  slug String @unique

  createdAt DateTime @default(now())
  updatedAt DateTime @default(now()) @updatedAt

  /// The pretty name for the game
  displayName String

  /// What the current SHA for the JS/files looks like
  assetsSha String

  /// Name of the function we should run
  exposedGlobalFunction String @default("runGameWithHost")

  ...

[dthyresson]

Nice work,

Thanks! @orta

I fully describe my prisma models with /// which also propogates into JSDocs,

Interesting.

Turns out Prisma does parse the schema in what it calls the DMMF document and each field has a name, type and .... documentation.

For example:

model WorldCity {
  /// The underlaying ID
  id           String   @id @default(uuid())
  /// Created at timestamp
  createdAt    DateTime @default(now())
  /// Created at timestamp
  updatedAt    DateTime @updatedAt
  /// The id in the SimpleMaps service
  simpleMapsId BigInt   @unique
  /// The name of a city
  city         String
  /// The name of a city in ASCII
  cityAscii    String
  /// Geocordinates of a city, latitude
  lat          Float
  /// Geocordinates of a city, longitude
  lng          Float
  /// Country in which the city is located
  country      String
...

Which I can then use to generate:

"""Representation of WorldCity."""
type WorldCity {
  """
  WeatherReport
  
  Description for WeatherReport.
  """
  WeatherReport: [WeatherReport]!

  """
  adminName
  
  Description for adminName.
  """
  adminName: String

  """
  capital
  
  Description for capital.
  """
  capital: String

  """
  city
  
  The name of a city
  """
  city: String!

  """
  cityAscii
  
  The name of a city in ASCII
  """
  cityAscii: String!

  """
  country
  
  Country in which the city is located
  """
  country: String!

  """
  createdAt
  
  Created at timestamp
  """
  createdAt: DateTime!

  """
  id
  
  The underlaying ID
  """
  id: String!

  """
  iso2
  
  Description for iso2.
  """
  iso2: String!

  """
  iso3
  
  Description for iso3.
  """
  iso3: String!

  """
  lat
  
  Geocordinates of a city, latitude
  """
  lat: Float!

  """
  lng
  
  Geocordinates of a city, longitude
  """
  lng: Float!

  """
  population
  
  Description for population.
  """
  population: Int

  """
  simpleMapsId
  
  The id in the SimpleMaps service
  """
  simpleMapsId: BigInt!

  """
  updatedAt
  
  Updated at timestamp
  """
  updatedAt: DateTime!
}

So, if there is a comment doc in Prisma, I use that or default.

Great idea!

[dthyresson]

Have added docs option to optionally generate the SDL comments via sdl and scaffold generators. Defaults to false so no docs generated. Except for Redwood root schema and built in auth Directives which have comments.

[Tobbe]

Mostly want to default to single-line comments whenever possible to make it less verbose/overwhelming

[dthyresson]

The GraphQL spec says that the contents of the block string can be markdown, so I'm not sure why it's throwing. 🤔 Can you reproduce?

I don't think you can use any markdown.

To allow GraphQL service designers to easily publish documentation alongside the capabilities of a GraphQL service, GraphQL descriptions are defined using the Markdown syntax (as specified by CommonMark). In the type system definition language, these description strings (often BlockString) occur immediately before the definition they describe.

It just says that you can use the "block string" which is mark of markdown.

I tried and got errors. But I think that is expected.

Another suggestion (maybe similar to what @Tobbe was suggesting): maybe we should make field comments use only one set of quotes instead of three? To match the example in the GraphQL spec: http://spec.graphql.org/draft/#example-916f4. Prettier seems to be forcing triple-quote descriptions onto their own line, but it leaves single-quote descriptions alone. That would keep the file from getting too big too fast. Thoughts?

Done!

[dthyresson]

I haven't gotten to the docs yet, just focused on the code

@jtoar I've updated the docs to match the quotation use. Should be good to go.