Postman Spec Hubがリリースされたのは2025年4月。すでに多くの人が使い始めているとは思いますが、API設計に本気で取り組むなら、一度しっかり触っておきたい機能のひとつです。今回は、そのSpec Hubの魅力や機能、APIファースト開発のハブとしてのSpec Hubについてわかりやすく解説します。
Spec Hubとは？
Spec Hubは、一言でいえば、「高機能なAPI仕様エディター」ですが、単なるAPI仕様エディターに留まりません。仕様の作成から整理、レビュー、モック化、テスト生成まで、APIファースト開発に必要な一連の作業をここを起点に進められる、まさにハブとしての役割を持っています。
Spec Hubが提供する機能
Spec Hubの全体イメージ
サポートAPI仕様フォーマット
まず、対応フォーマットとしてはOpenAPI 2.0／3.0／3.1の主要バージョンをしっかりサポートしており、仕様を複数ファイルやフォルダーに分割して管理するような大規模APIの運用にも対応しています。ローカルで複雑な設計をしている場合でも、そのままの構造でSpec Hubに持ち込めるので、移行もスムーズです。なお、Spec Hubは他にも非同期型APIの標準フォーマットであるAsyc APIもサポートしています。
- OpenAPI 2.0,3.0,3.1とAsyncAPI
- マルチファイル構成OpenAPIもOK
快適なAPI仕様ファイルの編集
編集体験はかなり快適です。サイドバーのアウトラインで必要な場所へすぐ飛べたり、コマンドパレットで仕様を一気に検索したりできるので、長いYAMLを手作業でスクロールするようなストレスが減ります。
また、スニペット機能であらかじめ整形されたテンプレートを追加したり、JSONのリクエスト・レスポンスからスキーマを自動生成したりと、細かい作業が驚くほど効率化されています。
さらに、編集しながらリアルタイムにドキュメントのプレビューが見られます。仕様を書き換えた結果が即座にドキュメントとしてどう見えるかを確認できるので、文書の整合性を保ちやすくなります。
OpenAPI仕様・コレクション間の双方向生成・更新
Spec Hubの強みとしてひとつ大きいのが、OpenAPIとPostmanコレクションの双方向同期です。
編集している仕様の画面右上にある「Generate Collection」ボタンをクリックすると、仕様からコレクションを作成できます。もちろん、コレクション作成後に仕様を変更したらその変更内容を一度生成したコレクションに反映させることもできます。
また、逆に、仕様から作成されたコレクションをアップデートした場合、そのコレクションからの変更内容を元に仕様（OpenAPI仕様）をアップデートすることもできます。コレクションを変更したら、下図のようにコレクションの「概要」ページの仕様 (Specification)セクションに「アップデート」ボタンが表示されるので、これをクリックすることでコレクションの変更を仕様に反映できます。
仕様と実装がズレてくる問題、いわゆるAPIドリフト問題は、 API開発ではなかなか避けられませんが、この仕組みを活用すると、仕様と同期されたコレクションでAPIのテストを行うことで、ズレを起こしづらくできます。
シンタックスとガバナンスルールチェック
Spec Hubは、リアルタイムで構文チェックを行います。OpenAPIの仕様を書いている最中でも、文法ミスや記述の間違いをエディター上で即時に検出してくれるので、書き終えてから大量のエラーに気づくなんてことが大幅に減ります。
さらにSpec Hubの大きな強みのひとつが、APIガバナンスルールの検証です。これは、チームや組織で定めたAPI設計ガイドライン（命名規則、レスポンス構造、ステータスコードの使い方など）をルールとして登録しておくと、仕様の中で違反している箇所を自動で検出してくれる仕組みです。
ガバナンスルールの検証が有効だと、仕様編集画面の下部にある「Governance」というタブに、違反内容と発生箇所に関する情報（下記）が一覧で表示されます。
- 違反しているルール
- そのルールに引っかかっている件数
- どこが問題なのかの説明
- そして、問題が発生している行（複数ファイル構成でもファイルパス含む）
これにより、どの部分を直せばよいかが一目瞭然であり、検出された各違反項目をクリックすると、該当箇所へジャンプできるので修正作業も迷いません。
企業や組織でAPIガイドラインを運用している場合、この仕組みはとくに強力です。人間の目だけではどうしても見落としがちな細かいルール違反も自動で拾い上げてくれるため、レビューの負荷が軽くなり、仕様の品質も安定します。
ガバナンスルール検証は Postman Enterprise プランでのみ利用できます
チーム開発を支える機能
Postmanには強力なロールベースのアクセス制御機能があるため、誰が編集できるか、誰が閲覧のみかといった権限管理を柔軟に設定できます。API仕様をしっかり共同で管理し、ブラックボックス化するのを防いでくれます。
APIファースト開発のハブとしてSpec Hub
APIファースト開発では、利用者のニーズを満たしたAPIコントラクトを設計するところを目標としてますが、最初から利用者ニーズを満たしたAPIを設計するのは至難の技です。
まずAPIの姿をしっかり決めることが最初のステップになりますが、そのためには、設計段階で仮説検証のループを高速に回す必要があります。
典型的な流れはこんな感じです：
- APIで実現したいゴールを決める
- APIコントラクト（仕様）を定義する
- モックやテストでふるまいを検証する
- ドキュメントとして公開し、利用者へ伝える
この流れを何度も往復しながら、より良いAPIに育てていきます。
Spec Hubは、このループの中心に置けるように設計されています。仕様を編集すれば、そこからコレクションを生成し、モックを作れたり、テストが作られたり、ドキュメントが更新されたりと、Spec HubをAPIファースト開発のハブとして展開できます。
なお、APIファースト開発について学びたい方に最適な一冊が出版されます。興味のある方はぜひ予約・購入してみてください。
「APIファースト Postmanで学ぶ効率的かつ柔軟な開発アプローチ」（翔泳社）2025/12/22 発売予定
Spec Hubの学習教材
Spec Hubを活用したAPI設計について実際に手を動かして学びたい方、「Postmanワークショップ「API設計入門」がオススメです。API設計の基礎からSpec Hubを使ったハンズオンまで、ひととおりオンラインで学べる内容になっています。
直近で実施されたワークショップの内容は、こちらのページで公開されている資料から確認できます。
次回のオンラインワークショップを受講したい方は、ぜひ connpass の Postmanグループ に参加して、API設計入門ワークショップの開催告知をお待ちください。
もし、Spec Hubの部分だけ触りたい場合は、以下のコレクションを自分のワークスペースへフォークして使ってください。
コレクション：ワークショップ - API設計入門 (https://t.ly/WxBbW)
コレクションの説明や各フォルダーを説明を読みながらハンズオンを進められるようになっています。
