GraphQL-MarkdownでGraphQLスキーマからドキュメントを自動生成する #GraphQL

はじめに

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に記述します。graphql-configが必要らしいのでインストールしましょう。schemaファイルのファイルパスとLoaderを修正します

$ npm install graphql-config

.graphqlrc

- 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を追加します。

docusaurus.config.js

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の生成もできるので、生成したファイルを静的ホスティングして共有することもできそうです。