こんにちは！API設計の現場で、こんなストレスを感じたことはありませんか？
- 「人によってパスの命名規則（kebab-caseなのかcamelCaseなのか）がバラバラ…」
- 「必須であるはずの `summary` や `description` が抜けているAPIドキュメントが放置されている…」
- 「レビューで毎回同じような指摘をするのに疲れた…」
APIファーストの開発において、OpenAPI（Swagger）定義書の品質担保は永遠の課題です。これを人間の目だけでチェックしようとすると、レビューのコストが跳ね上がりますし、何より楽しくありません。
今回は、API定義書の静的解析ツール「Spectral（スペクトラル）」を使い、GitHub Actionsと連携してプルリクエスト時に自動でLintチェック（規約違反の検知）を行う仕組みをハンズオン形式で解説します。
これをマスターすれば、機械的にチェックできる規約違反はすべてCI/CDパイプラインが弾いてくれるようになるため、人間は「ビジネスロジックやアーキテクチャの妥当性」という本質的なレビューに集中できるようになります。毎日の作業が劇的に楽になりますよ！
—
1. Spectralとは？なぜAPI開発の必須ツールなのか
Spectralは、JSONやYAML形式のドキュメント（OpenAPIやAsyncAPIなど）に対して、高度なルールベースの静的解析を行えるオープンソースのLintツールです。
JavaScript（Node.js）製で動作が非常に軽く、標準でOpenAPI 2.0 / 3.x の強力なルールセットを備えているだけでなく、自社の独自規約（「パスには必ず小文字を使え」「すべてのエラーレスポンスに `code` フィールドを含めろ」など）をカスタムルールとして簡単に定義できるのが最大の強みです。
—
2. 導入とローカル環境でのセットアップ
まずは、手元のマシンでSpectralを動かせるように環境を整えましょう。Node.js（LTS版推奨）がインストールされている前提で進めます。
インストール
グローバルにインストールしても良いですが、プロジェクトごとにバージョンを固定するため、今回はプロジェクトのローカル環境に導入します。
プロジェクトディレクトリの作成と初期化
mkdir openapi-lint-demo
cd openapi-lint-demo
npm init -y
Spectralのインストール
npm install –save-dev @stoplight/spectral-cli
動作確認用のOpenAPI定義書を作成する
実験用に、わざと規約違反（説明文の欠落など）を含んだ適当な定義書 `openapi.yaml` を作成してみましょう。
openapi.yaml
openapi: 3.0.3
info:
title: 注文管理API
# あえてversionを抜いてみる（Lintで検知させたい！）
paths:
/orders:
get:
summary: 注文一覧を取得する
# descriptionをあえて書かない
responses:
‘200’:
description: 成功
デフォルトルールでのLint実行
Spectralには、OpenAPIのベストプラクティスに基づいたデフォルトルールセットがあらかじめ用意されています。試してみましょう。
npx spectral lint openapi.yaml
実行すると、以下のように「情報（info）や説明（description）が足りないよ」といった警告やエラーがコンソールに美しく出力されます。
C:\project\openapi-lint-demo\openapi.yaml
4:3 warning info-description OpenAPI object info “description” should be present. info.description
7:5 error path-keys-no-trailing-slashes Path keys must not end with a slash. paths./orders
8:5 warning operation-description Operation object should have a “description” member. paths./orders.get
✖ 3 problems (1 error, 2 warnings)
これがローカルでの基本的な流れです。非常にシンプルですね！
—
3. 自社専用ルール（カスタムルール）の定義
デフォルトのルールだけでも十分強力ですが、実務では「チーム独自の命名規則」や「セキュリティ要件」を強制したい場面が多々あります。ここでは、カスタムルールを追加してみましょう。
プロジェクトのルートに `.spectral.yaml` という設定ファイルを作成します。
.spectral.yaml
extends: [spectral:oas] # Stoplightが提供するデフォルトのOpenAPIルールを継承する
rules:
# ルール1: すべてのAPIパス（エンドポイント）はケバブケース（kebab-case）であること
kebab-case-paths:
description: “APIのパスはケバブケース（例: /user-profiles）を使用してください。”
given: “$.paths[?(@property =~ /\\/{2,}/)]” # パスの書式チェック用表現など
# 簡易的に、特定の文字が含まれていないかなどをチェックするカスタム関数を設定可能
# 今回は分かりやすく「tagsが必ず設定されていること」を必須にするルールに変更してみましょう
# ルール2: すべてのオペレーションには必ず ‘tags’ が1つ以上設定されていること
operation-tag-defined:
description: “すべてのエンドポイント（GETやPOSTなど）には、グループ化のための ‘tags’ を必ず1つ以上設定してください。”
severity: error # 違反時はビルドエラーにする
given: “$.paths[][get,post,put,delete,patch]”
then:
field: tags
function: truthy
この設定ファイルを置いた状態で再度 `npx spectral lint openapi.yaml` を実行すると、独自の `operation-tag-defined` ルールが適用され、tagsが設定されていない箇所がエラーとして検知されるようになります。
—
4. GitHub ActionsでPR時に自動Lintチェックを走らせる（本丸）
ローカルでチェックできるようになったら、次はこれをCI/CDパイプラインに組み込んで自動化します。
開発者がGitHubにコードをプッシュし、プルリクエストを作成したタイミングで自動的にSpectralが走り、規約違反があればマージをブロックする仕組みを作りましょう。
プロジェクトのルートディレクトリに以下のディレクトリとファイルを作成します。
.github/
workflows/
lint-openapi.yml
ファイルの中身は以下のように記述します。
.github/workflows/lint-openapi.yml
name: OpenAPI Lint Check
mainブランチへのPR、またはmainブランチへのプッシュ時に実行
on:
pull_request:
branches: [ main ]
push:
branches: [ main ]
jobs:
lint:
name: Spectral Lint
runs-on: ubuntu-latest
steps:
# 1. リポジトリのコードをチェックアウト
- name: Checkout code
uses: actions/checkout@v4
# 2. Node.js環境のセットアップ
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: ’20’
cache: ‘npm’
# 3. 依存関係のインストール
- name: Install dependencies
run: npm ci
# 4. SpectralによるLint実行
- name: Run Spectral Lint
run: npx spectral lint “openapi.yaml” –ruleset .spectral.yaml
たったこれだけの設定で、GitHub上のCI環境にSpectralの検査網を構築できます。
実際の挙動
この状態で、ルールに違反したOpenAPI定義書をGitHubのブランチにプッシュし、PRを作成してみてください。
GitHub Actionsが数秒で動き出し、見事にテストが失敗（Red）して、コンソールにどの行がルール違反であるかが詳細に表示されます。
修正版をコミットしてプッシュし直せば自動でGreenになり、安心してレビュー・マージに進むことができるようになります。
—
5. 現場で役立つ実践知見（まとめ）
API開発において、品質の担保は「個人の意識の高さ」に頼ってはいけません。仕組みで強制すること、そしてフィードバックループを極限まで短くすることが成功の鍵です。
最後に、現場でSpectralを運用する上での知見をいくつかシェアします。
1. 最初はWarningから始める
いきなりすべてのルールを `error` にすると、既存の大量の定義書が引っかかり、チームからブーイングを受けます。最初は `warning` からスタートし、徐々にルールを厳格化（error昇格）していくのが現場に馴染ませるコツです。
2. VS Code拡張機能と組み合わせる
開発者がCIが落ちるのをわざわざ待たなくてもいいように、VS Codeを使っているメンバーには “Spectral” 拡張機能 のインストールを義務付けましょう。コーディングしているリアルタイムでエディタ上に波線でエラーが表示されるため、開発体験が爆発的に向上します。
「規約違反の指摘」という人間がやらなくていい機械的な作業はすべてSpectralとGitHub Actionsに任せて、私たちはもっとクリエイティブで楽しい設計の議論に時間を使いましょう！
あなたのチームのAPI開発が、より美しく、強固なものになることを応援しています。