環境

spectaql 2.0.4

ドキュメント生成ツール SpectaQL

私は GraphQL API のドキュメント生成に SpectaQL を利用しています。
GraphQL スキーマからドキュメントを自動生成してくれるツールです。

ページ内リンクを貼る

API の Description を書いていると、別の Type や Field の情報を前提に説明したい場合や、何度も同じ説明を書きたくないので、一箇所に説明を書いて関連箇所から参照させたい場合があります。
こういう場合にページ内リンクが使えると便利です。

SpectaQL は、標準で Query や Mutation、任意の Type などにアンカーを出力してくれます。
これらへのリンクを貼りたい場合は、単純にアンカー名を Markdown で指定するだけです。

種類	アンカー名
Query	`query-{queryName}`
Mutation	`mutation-{queryName}`
Subscription	`subscription-{queryName}`
Type, Union, Enum, etc	`definition-{typeName}`

ただ、フィールドにはアンカーが出力されません。

フィールドにアンカーを設置する

フィールドのアンカーが無いなら、自分で書いてしまえば良いわけです。

schema.graphqls

type User {
  """
  <a id="field-User-name"></a>
  ユーザ名
  """
  name: String!
}

...

type Foo {
  """
  ...
  詳しくは [User#name](#field-User-name) を参照。
  """
  bar: String
}

応用として、 spectaql/config.yml などで共通仕様を記載するときに見出しにアンカーを設けておけば、任意の位置に参照を埋め込むことができるようになります。

spectaql/config.yml

info:
  title: ほげほげ API
  description: |-
    これは、ほげほげ API の仕様書です。

    <a id="AboutErrors></a>
    ## エラー仕様
    | エラーコード | 発生理由 |
    | -------- | ------- |
    | ERROR_1  | xxxx |
    | ERROR_2  | yyyy |

まとめ

Markdown の仕組みをわかっていれば当たり前の話ですね。
Field にページ内リンクしたいなぁと思いつつも、自分でアンカーを設置する発想が今までありませんでした。(アホですみません)