同じチームの2人のエンジニアが同じ週に2つのエンドポイントをリリースしました。片方はcreated_atを返し、もう片方はcreatedAtを返します。あるものは?page=2でページネーションし、別のものは?offset=20でページネーションします。エラーの格納場所も異なり、トップレベルのerrorオブジェクトに入れるものもあれば、message文字列をインライン化するものもあります。レビューアがロジックを読み、命名規則を読んでいないため、どちらもコードレビューを通過します。6ヶ月後、あなたのAPIサーフェスはまるで5つの異なる企業によって書かれたかのように見え、すべてのクライアント統合で特別な対応が必要になります。
OpenAPIリンターは、このような逸脱がリリースされる前に検出するために存在します。これはOpenAPIドキュメントを読み込み、一連のルール（オペレーションには説明が必要、スキーマには例が必要、プロパティ名はケース規則に従う、すべてのレスポンスはメディアタイプを宣言する、など）と照合し、ルールが破られている場合にビルドを失敗させます。これはJavaScriptのESLintやRubyのRuboCopと同じ考え方で、アプリケーションコードではなくAPIコントラクトを対象としています。コードの書式設定が自動化されるようにAPI設計レビューも自動化できたら、と願ったことがあるなら、まさにリンターがそれを行うものです。
OpenAPIリンターが実際にチェックすること
リンターは、稼働中のサーバーではなく、仕様ファイルに対して動作します。openapi.yamlを指定すると、すべてのパス、オペレーション、パラメーター、スキーマ、レスポンスを一つずつ見て回り、ルールを適用します。ルールはいくつかのカテゴリーに分けられます。
有効性。これはそもそも有効なOpenAPIドキュメントですか？すべての$refは解決されますか？必須キーワードは存在しますか？これは単純なスキーマ検証と重複する部分であり、ほとんどのリンターは他の何よりもまずこれをベースラインとして行います。
完全性。すべてのオペレーションにoperationId、サマリー、説明はありますか？すべてのパラメーターは自身の説明をしていますか？すべてのスキーマはexampleを持っていますか？これらは生成されるドキュメントやSDKを実際に利用可能にするためのルールであり、人間が最も忘れがちな点です。
一貫性。これが本当の醍醐味です。プロパティ名が一つのケース規則に従っているか。パスセグメントが複数形の名詞であるか。エラーレスポンスが共通の形式を共有しているか。すべての2xxレスポンスがapplication/jsonを宣言しているか。ステータスコードがHTTP仕様の意図通りに使われているか。これらは単独ではバグではありませんが、これらが揃うことで、設計されたAPIと感じるか、寄せ集められたAPIと感じるかの違いが生まれます。
ハウススタイル（社内規定）。あなた独自の慣習です。すべてのエンドポイントにタグを付ける必要があるかもしれません。DELETEが204を返すべきかもしれません。内部専用フィールドにはプレフィックスを付ける必要があるかもしれません。これらは他の誰も持っていないルールであり、これらを書く能力が、使いやすいリンターと使いにくいリンターを分けるものです。
ルールには、error（エラー）、warning（警告）、info（情報）、hint（ヒント）という重大度があります。エラーはビルドを失敗させますが、警告は表示されるもののビルドは通過します。この重大度設定があることで、既存のAPIに対してリンティングを導入する際、初日から4,000件もの違反に埋もれることなく進めることができます。最初はすべてを警告として開始し、最悪のものを修正し、その後、徐々にルールをエラーに昇格させていきます。これらのルールがなぜ重要なのか、そしてチームが大規模にそれらをどのように適用しているのかという概念的な側面については、トップ企業がAPI設計の一貫性を確保する方法に詳しい背景が記載されています。
主要なOpenAPIリンターの選択肢
知っておくべきツールと、それぞれがどのような位置付けであるかの正直な見解をご紹介します。
Spectral
Stoplight製のSpectralは、デファクトスタンダードです。これはOpenAPI 2.0および3.x（ならびにAsyncAPI、およびJSONPathを介したあらゆるJSONまたはYAML）をリンティングするオープンソースのCLIおよびライブラリです。常識的なルールを網羅する組み込みのspectral:oasルールセットが付属しており、その真の強みはカスタムルールにあります。YAMLファイル内でJSONPathスタイルのgivenセレクターとthen関数を使用して、何をチェックするかを記述します。組み込み関数の大規模なカタログ（truthy、pattern、casing、length、enumeration）があり、宣言型形式では表現できないロジックが必要な場合はJavaScriptに切り替えることもできます。
長所：どこでも使われており、最大のルールエコシステムを持ち、VS Codeなどのエディタ拡張機能が存在し、Nodeが動作するあらゆる場所で実行できます。業界全体が認識するツールを求めるなら、これです。トレードオフとして、自明でないルールを書くにはJSONPath、そして最終的にはSpectralの関数APIを学ぶ必要があります。オーサリングについて深く掘り下げたい場合は、TypeScriptでカスタムSpectralルールを構築するで完全なチュートリアルを用意しています。
最小限の.spectral.yaml：
extends: ["spectral:oas"]
rules:
operation-operationId: error
operation-description: warn
property-casing:
description: Properties must be camelCase
given: $.components.schemas..properties[*]~
severity: error
then:
function: casing
functionOptions:
type: camel
実行方法：
npx @stoplight/spectral-cli lint openapi.yaml
Redocly CLI
RedoclyのCLI は、リンティングとバンドル、ドキュメントプレビューをバンドルしています。そのリンターはredocly.yaml設定を読み込み、組み込みルールセットを提供し、設定可能なルールセットとJavaScriptで書かれたカスタムプラグインをサポートします。すでにRedoclyをドキュメンテーションに使用しているチームは、依存関係を追加することなく、同じツールチェーン内でリンティングを利用でき、組み込みルールはドキュメントが良好にレンダリングされることに重点を置いています。
長所：ドキュメントとバンドルのワークフローとの密接な統合、適切なデフォルト設定、そしてRedoclyエコシステムに慣れている人にはしっくりくる設定形式。もしそうでない場合、ルールライブラリはSpectralよりも小さく、カスタムルールに関する情報はあまり広く文書化されていません。
npx @redocly/cli lint openapi.yaml
Vacuum
Vacuumは、Goで書かれた新しいリンターで、速度を重視して構築されています。Spectralのルールセットと互換性があるため、既存の.spectral.yamlを指し示し、大規模な仕様に対しても同じチェックをはるかに高速に実行できます。数十もの大規模なAPIドキュメントを持つモノレポでは、実行時間の違いは顕著です。
長所：高速、Spectralルールセット互換、Nodeランタイム不要の単一バイナリ。仕様が小さい場合、速度向上は目に見えませんが、エコシステムやエディタツールはSpectralよりも新しいため、ゼロからの選択というよりはCIの高速化ツールとして最も魅力的です。
Swaggerとopenapi-spec-validator
リンターと混同しないように言及しておきます。Swagger Editorやswagger-cli/openapi-spec-validatorは、ドキュメントが有効なOpenAPIであるかどうかをチェックします。これは有効性のみであり、一貫性やハウススタイルではありません。OpenAPI仕様はそれを禁止していないため、すべてのプロパティが異なる名前を持つ仕様でも喜んで合格させてしまいます。検証は必要ですが、それは最低限のことであり、最高の目標ではありません。Swaggerファミリーのツールと完全な設計プラットフォームのどちらを選択するかで迷っている場合は、APIをテストするSwaggerの代替ツールでトレードオフが説明されています。
Apidogでの設計時チェック
上記のツールはファイルが存在した後に実行されます。不整合を検出するもう一つの場所は、ファイルが存在する前、エンドポイントを設計している間です。Apidogはデザインファーストのプラットフォームです。ビジュアルエディターでエンドポイントとデータスキーマを構築し、作業を進める中でプロジェクトの内部一貫性を保ちます。再利用可能なデータスキーマは、エンドポイントごとに再定義するのではなく、同じモデルがどこでも参照されることを意味し、命名のずれの発生源を根絶します。共有レスポンスコンポーネントも、エラーの形状に関して同様の役割を果たします。
ApidogはSpectralルールセットの直接の代替品ではありません。もし.spectral.yamlルールをコミットしているなら、それらを引き続き実行してください。Apidogが変えるのは、リンターがそもそもどれだけの問題を発見するかという点です。設計インターフェースが再利用を強制すると、リンターは膨大な違反の壁から、たまに見つかる程度のものへと変わります。そしてApidogは標準的なOpenAPI 3.xをインポートおよびエクスポートするため、CIでSpectralやVacuumに渡すファイルは同じ成果物となり、2つのレイヤーが競合するのではなく積み重なって機能します。
今日から使えるリンター設定
優れた設定では、それぞれ異なる役割を持つ3つの場所でチェックを実行します。エディタは即座にフィードバックを与えます。pre-commitフックは明らかな間違いをローカルで阻止します。CIは誰もスキップできないゲートです。各レイヤーを説明します。
レイヤー1：エディタ
Spectral VS Code拡張機能をインストールし、リポジトリのルートに.spectral.yamlを追加します。拡張機能はこれを自動的に認識し、スペルミスが赤い波線で示されるのと同じように、仕様を編集する際に違反に下線を引きます。これは可能な限り安価なフィードバックループです。なぜなら、開発者はコミットになる前に問題を修正できるからです。他に設定するものはありません。リポジトリ内のファイルが、ルールの唯一の真実の源となります。
レイヤー2：pre-commit
壊れた仕様がリモートに到達しないようにフックを追加します。package.jsonスクリプトとGitフックを使用するだけで十分です。
{
"scripts": {
"lint:api": "spectral lint openapi.yaml --fail-severity=error"
}
}
# .git/hooks/pre-commit (or via husky)
#!/bin/sh
npm run lint:api || {
echo "OpenAPI lint failed. Fix the spec before committing."
exit 1
}
--fail-severity=errorフラグが重要な部分です。これは、リンターに対しエラーの場合にのみゼロ以外の終了コードを返すよう指示するため、警告が表示されてもコミットをブロックすることはありません。これにより、ルールを昇格させている間もフックを使用可能な状態に保つことができます。
レイヤー3：CI
これは重要なゲートです。なぜなら、チームメイトが--no-verifyで迂回できない唯一の場所だからです。GitHub Actionsのステップ例：
name: API lint
on: [pull_request]
jobs:
spectral:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npx @stoplight/spectral-cli lint openapi.yaml --fail-severity=error
仕様がエラーレベルのルールに違反するとジョブは失敗し、プルリクエストには赤いチェックが表示され、誰かが修正するまでマージはブロックされます。これが強制メカニズムの全体です。ダッシュボードも、しつこい通知もありません。ルールはパスするか、しないかのどちらかです。
レイヤー4：仕様が記述するAPIのテスト
リンターは、仕様が適切に構成され一貫性があることを証明します。しかし、実行中のAPIが仕様と一致するかどうかについては何も語りません。このギャップに契約のずれが隠れています。美しくリンティングされたドキュメントが、3リリース前にサーバーがサポートを停止した動作を記述している場合などです。これを解消するには、同じパイプラインでライブAPIに対してテストを実行します。
ここに、リンターの隣にApidog CLIが適合します。これはapidog-cliというnpmパッケージであり、Apidogのテストシナリオをコマンドラインから実行し、リンティングステップの直後にCIに組み込むことができます。
npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,junit
apidog runコマンドは、テストが失敗するとゼロ以外の終了コードを返します。これはすべてのCIステップが依存するのと同じ規約であり、リンティングの失敗と同様に、テストの失敗もマージをブロックします。-r junitレポーターは、CIダッシュボードがパス/フェイルツリーに解析するXMLを出力し、-eは同じシナリオを複製することなくステージング環境や本番環境に向けます。CLIはOpenAPI 3.xドキュメントをimportすることもできるため、リンターがチェックするファイルとApidogがテストするファイルは同じです。レポーターや終了コード処理を含む完全なパイプラインパターンについては、CI/CDパイプラインでApidog CLIを実行するガイドを参照してください。特にGitHubを使用している場合は、GitHub ActionsでのApidog CLIにコピー＆ペースト可能なワークフローがあります。
まずリンティング、次にテストです。リンティングステップは高速で設計上の問題を検出し、テストステップはより低速で動作上の問題を検出します。これらを2つのステージとして実行することで、プルリクエストは両方のチェックをクリアする必要があります。
苦労せずにルールセットを選択し導入する方法
ツールを選ぶのは簡単な部分です。既存のAPIに導入する段階でチームは行き詰まります。なぜなら、成熟した仕様で最初の実行をすると何百もの違反が返され、明らかな反応としてすべてを無効にしてしまうからです。
ゼロからルールを開始したり、すべてのルールをエラーレベルで開始したりしないでください。組み込みルールセット（spectral:oas）から始め、追加するすべてのルールをwarnに設定します。実行し、カウントを読み、まず有効性エラーを修正します。これらは実際のバグだからです。次に、クライアントにとって最も重要な2つまたは3つの一貫性ルール（通常はプロパティのケース規則と単一のエラー形式）を選び、それらのみをerrorに昇格させます。それ以外のすべては警告のままにします。各スプリントで、コードベースが追いつくにつれて、1つか2つの警告をエラーに昇格させていきます。四半期以内には、ルールセット全体が適用され、誰も出荷を止めることなくそこに到達できます。
ハウススタイルのルールは控えめに作成してください。すべてのカスタムルールは、誰かが維持し、次の採用者に説明しなければならないコードです。ルールは、違反が実際に問題を引き起こしたときにのみその場所を獲得するべきであり、起こるかもしれないという理由だけではありません。作成するルールについては、設計レイヤーに依存して、それらが稀にしか発生しないようにしてください。例えば、スキーマが中央の定義から再利用されている場合、名前が定義されている場所が1つであるため、プロパティのケース規則はほとんどトリガーされません。どのルールが強制する価値があり、どれが些細な議論であるかという概念的な枠組みは、API設計のベストプラクティスで説明されています。
生のYAML以外の言語で設計する場合でも、リンターは適用されます。TypeSpecはOpenAPIにコンパイルされ、出力されたドキュメントも同様にリンティングします。リンターはファイルがどのように作成されたかではなく、その内容のみを気にしません。
より大きな設計ループにおけるリンターの位置付け
リンターはデザインファーストのワークフローにおける一つの制御要素であり、すべてではありません。完全なループは、コントラクトの設計、リンティング、クライアントがそれに合わせて開発できるようにモック、それに対する実装のテスト、そしてそこからのドキュメント公開です。いずれかのステップをスキップすると、他のステップの価値が失われます。誰もモックしないリンティングされた仕様は、フロントエンドの開発を依然として妨げます。誰もテストしないモックされた仕様は、依然として現実から乖離します。
そのループでデザインを優先する理由は、リンティングが機能する理由と同じです。つまり、問題を修正するのが最も安価な場所で問題を検出するためです。設計ツールでプロパティ名を変更するのは1回の編集です。3つのチームが古い名前に対して出荷した後でそれを変更するのは移行作業です。リンターはファイルの一貫性を強制します。デザインファーストのプロセスは、ファイルが存在する前の決定段階で一貫性を強制します。シーケンスに関するより広範な議論については、APIファースト vs APIデザインファースト vs コードファーストがトレードオフを説明し、コントラクトファーストのAPI設計ツールがそれをサポートするツールについて解説しています。
Apidogは、そのループ全体を一つの場所でカバーします。再利用可能なスキーマで設計し、即座にモックし、CIでCLIを使ってテストし、標準化しているリンターのためにクリーンなOpenAPIをエクスポートします。リンターには依然として役割がありますが、捕捉すべき問題は少なくなります。