OpenAPIのLinter導入してPRで指摘するしくみを作った話（Spectral × reviewdog）

はじめに

こんにちは。株式会社ペライチ バックエンドエンジニアの船橋です。
当社では OpenAPI を使用して API 仕様書を管理していますが、チーム規模の拡大に伴い、仕様書の品質維持が課題となっていました。今回は、OpenAPI の Lint ツールである Spectral と、GitHub 上でコードレビューコメントを自動でつけてくれる reviewdog を組み合わせて、PR作成時に自動でAPI仕様の指摘を出すしくみを構築した経験を紹介します。

---

🧩 なぜこのしくみが必要だったのか？

OpenAPI を使って API 仕様書を管理している中で、以下のような具体的な課題に直面していました。

• エンドポイントやパラメータの命名ルールが人によってばらつく
• 重要な項目（operationId や description）の記述漏れが頻発
• レスポンス例の形式が開発者によって不統一
• PR レビュー時に、細かいルールまでチェックする工数が膨大

これらの課題により、API 仕様書の品質低下やレビュー工数の増大が発生していました。そこで、PR時に自動で指摘してくれるしくみを導入し、レビューの効率と品質を向上させることを目指しました。

---

🛠 使用したツール

• Spectral
  OpenAPI 仕様書に対してルールベースで Lint をかけるツール。

  • YAML ファイルでカスタムルールを定義可能
  • 豊富な組込みルールセット
  • エラーレベルの柔軟な設定（error/warning/off）

• reviewdog
  Lint 結果を GitHub の PR に自動でコメントしてくれるツール。

  • 差分に対してのみコメントが可能
  • 複数の Lint ツールに対応
  • GitHub Actions との親和性が高い

---

⚙️ 実装の流れ

1. .spectral.yaml の用意（Lintルールの定義）

extends: ["spectral:oas"]
rules:
  # 必須項目のチェック
  operation-description: error  # API 操作の説明必須
  operation-operationId: error # operationId の設定必須
  
  # カスタムルール
  custom-response-example:
    description: "レスポンスに例が含まれている必要があります"
    given: "$.paths[*][*].responses[*].content['application/json']"
    then:
      field: examples
      function: truthy

2. GitHub Actions ワークフローの作成

.github/workflows/openapi-lint.yml

name: Lint OpenAPI

on:
  pull_request:
    paths:
      - "openapi/swagger.yaml"  # OpenAPI 定義ファイルの変更時のみ実行

jobs:
  spectral-lint:
    runs-on: ubuntu-latest

    steps:
      - name: checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 差分比較のため完全な history が必要

      - name: install spectral
        run: npm install -g @stoplight/spectral-cli

      - name: setup reviewdog
        uses: reviewdog/action-setup@v1

      - name: spectral lint
        run: |
          spectral lint openapi/swagger.yaml --ruleset .spectral.yaml -f text | reviewdog -efm="%f:%l:%c %t%*[^ ] %m" -name="spectral" -filter-mode=diff_context -reporter=github-pr-review
        env:
          REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }}

このワークフローにより、以下の自動化が実現されました。

1. OpenAPI 定義ファイルが変更された PR を検知
2. Spectral による仕様書の Lint チェック実行
3. reviewdog による Lint 結果の PR コメント投稿

---

✅ 導入後の効果

• 記述ルールの統一と品質向上

  • operationId や description の記述漏れが激減
  • 命名規則の統一性が向上
  • レスポンス例の形式が標準化

• レビュー工数の削減

  • 形式的なチェックを自動化することで、レビュアーの負担の削減
  • 本質的な設計議論により多くの時間を割けるように

---

📝 まとめ

Spectral と reviewdog の組み合わせにより、以下の成果を達成できました。

1. API 仕様書の品質を自動的にチェック・維持
2. レビュー工数の削減と効率化
3. チーム全体のドキュメント品質の向上

特に、PR 上での即時フィードバックという形式が、開発者の学習とチームの品質向上に大きく貢献しています。

「API 仕様のレビューに時間がかかる」「人によって書き方がバラバラ」という課題をお持ちの方は、ぜひこのしくみを検討してみてください。

※最近では、Devin や Cline など生成 AI の導入が進んでおり、
以前は reviewdog が担っていたルールベースの指摘も、AI が自然にカバーできるようになってきました。