SpectralでOpenAPIをリンティング (もっと簡単な方法もご紹介)

同じチームの2人のエンジニアが同じ週に2つのエンドポイントを出荷します。一方はcreated_atを返し、もう一方はcreatedAtを返します。一方は?page=でページネーションし、もう一方は?offset=でページネーションします。どちらも単独では間違いではありません。しかし、これらが一緒になると、APIはまるで見知らぬ人によって組み立てられたかのように感じられ、それを利用するすべてのクライアントがそのコストを支払うことになります。OpenAPIファイルは問題なく検証され、パースされ、Swagger UIでレンダリングされ、SDKも生成されます。ただ一貫性がないだけであり、通常のバリデーターはそのことについて何も言及しません。

それこそが、リンターが埋めるべき正確なギャップです。バリデーターは「この仕様は法的に有効なOpenAPIか？」と問いに答えます。リンターは「この仕様は私たちが合意したルールに従っているか？」と問いに答えます。後者の問いに対する最も人気のあるオープンソースツールは、Stoplight社のJSONおよびYAMLドキュメント用リンターであるSpectralです。これは、組み込みのOpenAPIルールセットを搭載しており、独自のルールを記述でき、ターミナルやエディターから実行できます。APIスタイルガイドを適用するための無料でスクリプト可能な方法を求めているなら、Spectralが明白な最初の選択肢であり、このガイドではその適切な使用方法を示します。

それはまた、トレードオフも示しています。Spectralは、あなたが構築し、保守するルールセットです。YAMLルールを手書きすることなく、一貫性チェック、モックサーバー、実行可能なテストを1箇所で得たいチームにとって、Apidogはその作業を設計画面自体に組み込んでいます。まずSpectralを十分に評価し、その後にオールインワンのパスがいかに保守の手間を省くかを示します。

Spectralが実際にすること

Spectralは汎用リンターです。構造化されたドキュメントを指し示し、一連のルールを与えると、ドキュメントがルールに違反しているすべての箇所を、行番号と重大度とともに報告します。OpenAPIに特化したものではなく、OpenAPI、AsyncAPI、Arazzoをすぐに理解し、カスタムルールを使って任意のJSONまたはYAMLファイルをリントできます。

API作業においてこれが重要である理由は、組み込みのspectral:oasルールセットです。このルールセットは、OpenAPIの多くの慣習をエンコードしています。例えば、操作にはoperationIdがあるべき、infoオブジェクトには説明と連絡先が含まれるべき、タグは使用される前に定義されるべき、パラメーターは重複しないべき、といったものです。これを実際の仕様に対して実行すると、ほとんどの場合、最初の試行で警告のリストが表示されます。それらのどれもパーサーを壊すものではありませんが、すべてが仕様を扱いにくくします。

これは構造的なバリデーションとは異なる作業です。swagger-cliやRedoclyのようなツールは、ドキュメントがOpenAPIスキーマに準拠しているかどうかを答えます。Spectralは、その上でドキュメントが自社のスタイルに従っているかどうかを答えます。どちらも必要であり、これら2つのチェックはパイプライン内でクリーンに構成できます。OpenAPI仕様を検証する方法に関するガイドでバリデーションの部分を詳しく説明しており、この記事はスタイルと一貫性の部分についてです。

Spectralのインストールと初回リントの実行

Spectralはnpmパッケージとして提供されています。CLIは@stoplight/spectral-cliです。グローバルにインストールするには、以下を実行します。

npm install -g @stoplight/spectral-cli

Node.jsが唯一のシステム依存関係であるため、Nodeが既にインストールされているマシンやCIイメージであれば、それを実行できます。グローバルにインストールしたくない場合は、一時的なビルドランナーでnpx @stoplight/spectral-cli ...を使用できます。

Spectralは何をチェックすべきかを知るためにルールセットを必要とします。慣例として、作業ディレクトリに.spectral.yamlという名前のファイルを置きます。最もシンプルな有用なルールセットは、組み込みのOpenAPIルールを拡張するものです。

# .spectral.yaml
extends: ["spectral:oas"]

それでは、仕様をリントしましょう。現在のディレクトリに.spectral.yamlがある場合、Spectralはそれを自動的に検出します。

spectral lint openapi.yaml

または、ルールセットを明示的に指定します。

spectral lint openapi.yaml --ruleset .spectral.yaml

出力は意図的に読みやすく作られています。各発見は、行と列、重大度、トリガーされたルール、そして人間が読めるメッセージを示します。

openapi.yaml
  3:6   warning  info-contact      Info object should contain `contact` object.
  5:10  error    info-description   OpenAPI object info `description` must be present.

✖ 2 problems (1 error, 1 warning, 0 infos, 0 hints)

既存の仕様に対して最初の実行を行った時、ほとんどのチームはどれほど多くの乖離が生じているかに気づきます。ルールは強制されていなかったため、誰もそれに従っていなかったのです。

独自のルールを作成する

組み込みのルールセットは出発点であり、目的地ではありません。Spectralの真の価値は、チームの慣習を、変更ごとにマシンがチェックするルールとしてエンコードすることにあります。ルールには4つの要素があります：何を対象とするか（given、JSONPath式）、何をチェックするか（then、関数）、どの程度の重大度で報告するか（severity）、そして失敗したときに何と伝えるか（message）。

以下は、一般的な社内慣習であるケバブケースのパスを強制するルールです。

# .spectral.yaml
extends: ["spectral:oas"]
rules:
  paths-kebab-case:
    description: Paths should be kebab-case.
    message: "{{property}} should be kebab-case (lower-case, hyphen-separated)"
    severity: warn
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: "^(\\/|[a-z0-9-.]+|{[a-zA-Z0-9_]+})+$"

givenはすべてのパスキーを選択します。thenは組み込みのpattern関数を正規表現に対して実行します。パターンに失敗したものは、指定したメッセージとともに警告として報告されます。整数IDをUUIDで禁止したり、すべてのPOSTでエラー応答を要求したり、サーバーURLにバージョン番号を含めることを禁止したり、すべての操作に説明を必須にしたりできます。Spectralにはいくつかのコア関数（truthy、pattern、schema、length、enumerationなど）が用意されているため、ほとんどの慣習はコードを一切必要としません。

関数オプションでは表現できないロジックが必要な場合、SpectralではJavaScriptまたはTypeScriptでルールを記述し、カスタム関数をインポートできます。ここにツールの強力さがあり、同時に保守作業も始まります。そこまで深く掘り下げたい場合は、TypeScriptを使用したカスタムSpectralルールの構築に関する完全なチュートリアルを用意しています。

重大度とビルドの失敗

すべてのSpectralルールには、error、warn、info、またはhintの重大度があります。デフォルトでは、CLIはerrorを検出した場合にのみゼロ以外のコードで終了します。警告は表示されますが、実行は失敗しません。これは、レガシーな仕様をクリーンアップしている最中で、数千の警告がすべてのマージをブロックするのを避けたい場合には問題ありません。

仕様がクリーンになったら、ゲートを厳しくします。--fail-severityフラグが閾値を制御します。

spectral lint openapi.yaml --fail-severity=warn

これで警告も終了コード1を返すようになり、CIステップはこれを読み取って失敗とマークします。これがリンターを実際の品質ゲートに変えるメカニズムです。仕様がスタイルガイドから逸脱した瞬間、パイプラインはマージをブロックします。また、ルールセットで個々のルールの重大度を上書きすることもでき、気になるルールをwarnからerrorに引き上げたり、チームに合わないルールをoffに設定して無効にしたりできます。

CIでのSpectralの実行

誰かが思い出したときにだけ実行されるリンターは、ゲートではありません。ポイントは、すべてのプッシュで、クリーンなマシンで、全員に同じルールセットを使って実行することです。Spectralはこれを簡潔にします。以下は、仕様に触れるすべてのプルリクエストでリントを実行するGitHub Actionsジョブです。

name: Lint OpenAPI

on:
  pull_request:
    paths:
      - "openapi.yaml"

jobs:
  spectral:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: npm install -g @stoplight/spectral-cli
      - run: spectral lint openapi.yaml --fail-severity=warn

より豊富なレポートのために、SpectralはJUnit XMLを出力でき、ほとんどのCIダッシュボードはこれを合格/失敗ツリーにパースします。

spectral lint openapi.yaml -f junit -o results.xml

そのアーティファクトをダッシュボードに接続すれば、各貢献者は生のログを読むことなく、どのルールがどこで失敗したかを確認できます。構造チェック、リント、破壊的変更の検出を組み合わせたより広い視点が必要な場合、CIにおけるOpenAPIパターンは単一のツールを超えて一般化されます。仕様をコードとして扱うという考え方が、これらすべてを定着させるのです。

Spectralがあなたに多くのことを求める点

Spectralは得意なことをうまくこなします。正直なところ、それは一つのことしかせず、仕様のライフサイクルの残りはあなた自身がまとめ上げる問題となります。チームがデモを超えてこれを採用すると、いくつかの現実が明らかになります。

ルールセットはあなたが所有します。組み込みのspectral:oasルールは汎用的です。実際のスタイルガイドは、あなたが記述、レビュー、バージョン管理し、慣習の進化に合わせて最新の状態を保つカスタムルールに存在します。そのルールセットは、それ自身の保守負担を伴う小さなコードベースとなり、JSONPathとカスタム関数はチームの誰もが持っているスキルではありません。

それはドキュメントをリントし、API自体をリントするわけではありません。Spectralはファイルを読み取ります。実行中のサービスが仕様が約束するものを実際に返しているかどうかは教えてくれません。仕様はすべてのリントルールに合格しても、実装が数か月前に乖離したエンドポイントを記述している可能性があります。そのギャップを埋めるには、実際のリクエストを送信し、応答をアサートする必要がありますが、これは全く別のツールです。

それは長いチェーンの一部に過ぎません。リントの後も、フロントエンドチーム向けのモック、ドキュメントサイト、自動テストスイートが必要です。それぞれが別のツールとしてインストール、設定され、仕様と同期を保つ必要があります。リンターはそれらのどれについても知らないため、仕様は各段階で再度パースされ、再解釈されます。

これらはSpectralに対する批判ではありません。それは焦点を絞ったリンターであり、その範囲について正直です。しかし、「焦点を絞っている」ということは、統合作業があなたにかかることを意味します。

より簡単な方法：デザインサーフェスに組み込まれた一貫性

もう一つの道があります。一貫性を仕様が記述された後に付け足すリントステップとして扱うのではなく、Apidogはそれを仕様を記述するプロセスの一部として扱います。

ApidogはオールインワンのAPIプラットフォームです。単一のワークスペースで、スキーマの設計、リクエストのデバッグ、テストシナリオの構築、エンドポイントのモック、ドキュメントの公開が行えます。デザインがツール内で完結するため、入力中に一貫性チェックが行われます。ビジュアルデザイナーは、コンパイラが構文エラーに下線を引くように、構造上の問題が発生した瞬間にそれを表面化するため、コミットに達する前に修正できます。あなたは事後に別途リンターを実行しているわけではありません。エディターがリンターなのです。

より大きな違いは、下流のすべてです。あなたが設計したのと同じ契約が、モックサーバー、インタラクティブなドキュメント、そしてテストシナリオとなり、再パースや同期を維持するためのセカンドツールは不要です。パイプラインでこれらのチェックを行いたい場合、Apidog CLIはターミナルからヘッドレスでテストシナリオを実行し、失敗時にはゼロ以外のコードで終了します。これはリンターに求めていたゲート動作そのものですが、ファイルを読むだけでなく、実行中のAPIを契約に対してテストします。一つのnpmコマンドでインストールし、シナリオを指定するだけです。

npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenarioId> -e <environmentId> -r cli

これはSpectralが残したギャップを埋めます。Spectralはドキュメントがあなたのスタイルに従っていることを確認します。Apidog CLIは、実装がまだドキュメントと一致していることを確認します。すべてのフラグについては、apidog run --helpを実行するか、完全なCLIガイドを参照してください。

したがって、このトレードオフは現実的であり、明確に述べる価値があります。Spectralは、あなたが組み立てて保守する、無料でスクリプト可能、ベンダーニュートラルなリンターを提供します。Apidogは、一貫性、モック、ドキュメント、実行可能なテストを単一の真実の源から提供し、接続する手間がはるかに少なくなります。既存のツールチェーンにポータブルなリントステップが必要なだけであれば、Spectralは良い選択肢です。ツール自体のプロジェクトになることなく、ライフサイクル全体を維持したいのであれば、統合されたパスの方が長期的に見てコストが低くなります。

Spectral vs Apidogの比較

この表はスコアボードとしてではなく、意思決定の助けとして使用してください。適切な選択とは、ライフサイクルのどの部分を一つのツールに任せたいかに合致するものです。

よくある質問

Spectralは無料ですか？ はい。SpectralはApache 2.0ライセンスの下でオープンソースであり、Stoplightによって保守されています。CLI、組み込みのOpenAPIルールセット、カスタムルールの作成はすべて無料で利用できます。

Spectralは私の仕様が法的に有効なOpenAPIであることを検証しますか？ 部分的にです。組み込みのルールは多くの構造的な問題を検出しますが、Spectralはリンターであり、専用のスキーマバリデーターではありません。完全な構造的カバレッジのためには、バリデーターと組み合わせて使用してください。OpenAPI仕様を検証する方法に関するガイドでその側面をカバーしており、最適なOpenAPIバリデーターツールで各オプションを比較しています。

Spectralは実行中のAPIをテストできますか？ いいえ。Spectralは仕様ファイルのみを読み取ります。ライブAPIが契約と一致するかどうかを確認するには、Apidog CLIのような、実際のリクエストを送信し応答をアサートするランナーが必要です。

Spectralの警告でCIビルドを失敗させるにはどうすればよいですか？ spectral lint openapi.yaml --fail-severity=warnを実行します。デフォルトではerrorの重大度のみがビルドを失敗させますが、--fail-severity=warnを使用すると警告もゼロ以外の終了コードを返します。

SpectralとApidogの違いは何ですか？ Spectralは、あなたが設定し保守する、焦点を絞ったオープンソースのリンターです。Apidogは、設計、一貫性チェック、モック、ドキュメント、テストがすべて一体となったオールインワンプラットフォームであり、構築する手間が少なく、同期を保つ必要も少なくなります。設計ツールの状況に関する関連比較については、Apidog vs Swaggerを参照してください。

まとめ

Spectralは、単純なバリデーターが見過ごす現実の問題を解決します。それは、OpenAPI仕様をチームが合意した慣習と一貫させることです。@stoplight/spectral-cliをインストールし、spectral:oasを拡張し、いくつかのカスタムルールを追加して、--fail-severity=warnでパイプラインをゲートしてください。多くのチームにとってそれで十分であり、費用はかかりません。

費用は後になって現れます。それは、あなたが保守するルールや、リンターの周りに構築する残りのライフサイクルにおいてです。一貫性、モック、ドキュメント、実行可能なテストを単一の真実の源から得たいのであれば、Apidogをダウンロードし、チェックが既にサーフェスの一部となっている場所で仕様を構築してください。どちらの方法でも、目標は同じです。希望ではなく、マシンによって強制される、チーム全体が信頼できる仕様です。