SpectaQL を使って GraohQL スキーマから仕様書を作成

SpectaQL とは

GraphQL スキーマの静的ドキュメントを生成する Node.js ライブラリです。

スキーマからこんな感じのドキュメントが生成できます。

GitHub リポジトリ

anvilco/spectaql: Autogenerate static GraphQL API documentation

主な操作の流れ

主な導入流れは以下の様になるかと思います。

1. 設定
2. 実行

とても簡単ですが、設定ファイルが結構ややこしい印象です。（たくさんコメント書きました。）

設定

さて今回の本題はこちらになります。

最低限必要となるファイルは以下の 2 つです。

「/」をプロジェクトルートとした場合の構成です。

  /
　├ config.yml
　└ ●●.gql

●●.gql については通常の GraphQL スキーマなので説明は割愛します。

config.yaml

spectaql:
  # サイトの左上に表示されるロゴ画像
  logoFile: ./micware_logo.jpg
  # サイトのファビコン
  faviconFile: ./micware_favicon.jpg
  # すべてのサーバーを表示するか
  displayAllServers: true
  # spectaqlに設定することよって表示をカスタマイズできる
  themeDir: spectaql

introspection:
  # 説明文末尾のピリオドを削除
  removeTrailingPeriodFromDescriptions: true
  # GraphQLスキーマ定義ファイル
  schemaFile: ./schema.gql
  # メタデータファイル(右カラムVariablesやResponseの値を拡張表示させる際に必要)
  metadataFile: ./metadata.json
  # 右カラムのExmpleを動的に生成するモジュール()
  dynamicExamplesProcessingModule: ./examples/customizations/examples
  # 右カラムのquery名フォーマット
  queryNameStrategy: none
  # 右カラムqueryを何回層下まで表示するか
  fieldExpansionDepth: 10

  # gqlファイル内に@spectaql構文で書いた内容を反映するか
  spectaqlDirective:
    enable: true
extensions:
  # 右カラム
  graphqlScalarExamples: true

info:
  # ドキュメントの名前
  title: GraphQL API Reference
  # 説明
  description: Welcome to the party!
  # サービス利用規約
  termsOfService: https://www.example.com/terms
  # 連絡先
  contact:
    name: API Support
    url: http://www.example.com/support
    email: [e-mail]
  # ライセンス
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  # イントロダクション
  x-introItems:
    - title: Important thing 1
      description: Some important stuff we wanted you to know. Supports `markdown`

servers:
  # サーバー1
  - url: https://staging.example.com/graphql
    description: ステージング環境
  # サーバー2
  - url: https://example.com/graphql
    description: 本番環境
    production: true
    headers:
      - name: Authorization
        example: Bearer <YOUR_TOKEN_HERE>
        comment: Your foo from bar

実行

上の設定をいい感じに変えて

npx spectaql config.yml

  /
　├ config.yml
　└ ●●.gql

おわりに

以下のサンプル設定ファイルを元にわりと手探りで動作確認しないとダメでした。

spectaql/config-example.yml at main · anvilco/spectaql

ドキュメントが充実している有名ライブラリって素敵だなと思いました。