はじめに
OpenAPIをredoc等でドキュメント化するように、GraphQLのスキーマも見やすい形でドキュメント化して開発メンバーに共有することで、開発効率をあげることができます。
GraphQLスキーマからドキュメントを生成するライブラリはいくつかありますが、いくつか試したところGraphQL-Markdownがいい感じだったので紹介します。
実行環境
$ node -v
v22.2.0
$ npm -v
10.8.0
GraphQL-Markdownの良いところ
- ドキュメントが充実している
- specifiedByディレクティブが反映される
- カスタムディレクティブを反映できる
- メンテされている(2024/5現在)
やってみる
まずは適当なschema.graphql
を作成します。
scalar Date @specifiedBy(url: "https://scalars.graphql.org/andimarek/local-date")
interface Book {
"id"
id: ID!
"タイトル"
title: String!
"著者"
author: String!
"発売日"
publishedDate: Date!
"出版社"
publishedBy: Company!
}
type Comic implements Book {
"id"
id: ID!
"タイトル"
title: String!
"著者"
author: String!
"発売日"
publishedDate: Date!
"出版社"
publishedBy: Company!
"巻数"
vol: Int!
"ページ数"
pages: Int!
}
type Magazine implements Book {
"id"
id: ID!
"タイトル"
title: String!
"著者"
author: String!
"発売日"
publishedDate: Date!
"出版社"
publishedBy: Company!
"発行ナンバー"
issueNumber: Int!
"何月号か"
month: Int!
}
enum Company {
ABC_BOOKS
KYOTO_SHUPPAN
SHUEISHA
}
type Query {
"全ての本のリストを取得"
books: [Book]!
}
これをドキュメント化します。
基本的にはリファレンスに従っていけばOKです。
GraphQL-MarkdownはDocusaurusベースで作られています。DocusaurusはMeta社が作成したドキュメントの自動生成に特化した静的サイトジェネレーターだそうです。
- まずはテンプレートが用意されているので、それを使ってDocusaurusのセットアップをします
$ npm init docusaurus graphql-docs-example https://github.com/graphql-markdown/template.git
自動でファイルが生成されるので、これを修正していきます。
- 次にローカルのスキーマファイルに基づいてドキュメントを生成します。リファレンスによると、スキーマの読み込みはデフォルトでURL経由になっており、ファイルを読み取るには
@graphql-tools/graphql-file-loader
が必要らしいのでインストールします
$ cd graphql-docs-example
$ npm install @graphql-tools/graphql-file-loader
- 設定は
.graphqlrc
に記述します。schemaファイルのファイルパスとLoaderを修正します。
- schema: 'https://api.react-finland.fi/graphql'
+ schema: '../schema.graphql'
extensions:
graphql-markdown:
baseURL: '.'
homepage: 'static/index.md'
loaders:
- UrlLoader: '@graphql-tools/url-loader'
+ GraphQLFileLoader: '@graphql-tools/graphql-file-loader'
docOptions:
frontMatter:
pagination_next: null
pagination_prev: null
printTypeOptions:
deprecated: 'group'
-
npm run doc
でドキュメントを生成し、ローカルサーバーを立ち上げて確認します。ブラウザが立ち上がり、schema.graphql通りのドキュメントになっていれば成功です。$ npm run doc $ npm run start
GraphQL-Markdownの良いところとして、「@specifiedByが反映される」が挙げられます。いくつかドキュメント生成ツールを試しましたが、specifiedByが反映されたのはGraphQL-Markdownだけでした。
カスタムディレクティブの反映
また、GraphQL-Markdownはカスタムディレクティブをドキュメントに反映させることができ、これも良かったです。
例えばスキーマに以下を追加します。
directive @validate(description: String!) on INPUT_FIELD_DEFINITION
input ComicInput {
title: String! @validate(description: "1000文字以内")
}
リファレンス通り、docusaurus.config.js
を編集しdescriptorとtagを追加します。
const { directiveDescriptor } = require("@graphql-markdown/helpers")
...
plugins: [
[
"@graphql-markdown/docusaurus",
/** @type {import('@graphql-markdown/types').ConfigOptions} */
{
customDirective: {
validate: {
descriptor: (directive, node) =>
directiveDescriptor(
directive,
node,
"`${description}`",
),
tag: (directive, node) => ({ text: directive.name, classname: "badge--info" }),
}
},
},
],
],
graphql-markdown/helpers
も必要そうなので入れます。
npm i @graphql-markdown/helpers
これで再度docs生成とサーバーを立ち上げ、確認します。
$ npm run doc
$ npm run start
カスタムディレクティブはタグとして反映されるようです。文字列も反映されるのはいい感じです。
最後に
本番で使う場合は、npm run build
でHTMLの生成もできるので、生成したファイルを静的ホスティングして共有することもできそうです。