🐕‍🦺

【GraphQL】Apollo ServerのスキーマにMarkdown形式で色々かけるよ

2023/06/15に公開

GraphQL

はじめに

GraphQLでAPIスキーマの定義をドキュメント化するとき、エラー定義とか独自の情報を入れたいときがあるかもしれません。

色々ツールを探していたのですが、普通にMarkdown書けるみたいなのでそのやり方と、調べたドキュメンテーションツールについてもざっとまとめておこうかなと思います。

GraphQLとMarkdownについて

Markdownのspecificationにはいくつか種類がありますが、そのなかのCommonMarkという形式でスキーマ内に定義できます。

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.

GraphQL サービス設計者が GraphQL サービスの機能と並行してドキュメントを簡単に公開できるように、GraphQL 記述は Markdown 構文（CommonMark で指定されている）を使用して定義されます。型システム定義言語では、これらの説明文字列（多くの場合、BlockString）は、それらが説明する定義の直前に発生します。

https://commonmark.org/

実際にCommonMarkで定義してみる

スキーマの定義は以下にしてみました。
スペース2つで改行が挿入できます。

schema.graphqls

"""
**Bold**
  
# Header1
テキスト1
  
## Header2
テキスト2
  
### Header3
テキスト3
  
- List1
- List2
- List3
  
> Blockquote
  
[Link](https://www.google.com)
  
![Image](https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png)
  
"""
type Book {
  """
  Fieldのdescriptionはここに書く
  """
  title: String
  author: String
}

type Query {
  books: [Book]
}