API仕様書をSwaggerで作る OpenAPIの書き方と基本構造・ツールの使い分けを解説

「API仕様書をExcelで管理しているが、実装と食い違ってきた」「Swaggerで書けと言われたが、OpenAPIとの違いすら分からない」。API開発の現場で繰り返し起きている状況です。

OpenAPIは、HTTP APIの仕様を機械が読める形式で記述するための標準仕様です。そしてSwaggerは、その仕様を扱うためのツール群を指します。まずこの区別を押さえることが出発点になります。

この形式で書く最大の利点は、1つの定義ファイルから閲覧用のドキュメント、クライアントコード、モックサーバーまで生成できることです。仕様書が読み物で終わらず、開発の資産になります。

この記事では、SwaggerとOpenAPIの関係を整理したうえで、仕様書の基本構造、最小構成のサンプル、ツールの使い分け、そして運用でつまずきやすい点までを順に扱います。

確認したいポイント	結論	詳細
SwaggerとOpenAPIの違いは？	仕様がOpenAPI、ツールがSwagger	旧Swagger仕様が寄贈されOpenAPI仕様になりました。現在Swaggerはツール群の名称です。
何で書く？	YAMLまたはJSON形式	実務ではYAMLが多く使われます。テキストのためバージョン管理と差分確認ができます。
最低限必要な項目は？	openapiとinfo、そしてpathsなど	この3つがあれば仕様書として成立します。まず小さく書いて動かすのが早道です。
何が嬉しい？	画面とコードを自動生成できる	1つの定義から閲覧用ドキュメント、クライアント、モックサーバーを生成できます。

この記事でわかること

• SwaggerとOpenAPIの関係と、名称が2つ存在する経緯
• OpenAPI仕様書のトップレベル構造と、必須になる項目
• そのまま試せる最小構成のYAMLと、項目を足していく手順
• Swagger Editor、Swagger UI、Codegenなど関連ツールの役割と使い分け
• 仕様書とコードがずれる問題への対処と、運用で決めておくべきこと

システム開発とAI活用の進め方をまとめた資料を無料で配布しています 要件整理の進め方、開発や試験の依頼範囲の決め方、費用と期間の目安を1冊にまとめました。 社内での検討材料としてご活用いただけます。 ＞ 資料請求はこちら ※オンライン完結／しつこい営業は一切いたしません

SwaggerとOpenAPIの違い

最初につまずくのがこの2つの関係です。同じものを指しているように見えて、実際には仕様とツールという別のものを指しています。

OpenAPIは仕様、Swaggerはツール群

OpenAPI Specification（OAS）は、HTTP APIを記述するための標準的な仕様です。プログラミング言語に依存しない形式で、人と機械の双方がAPIの機能を理解できるようにすることを目的としています。

対してSwaggerは、その仕様を扱うためのツールの総称です。仕様書を書くエディタ、閲覧用の画面を生成するビューア、コードを生成するツールなどが含まれます。

「Swaggerで書く」という表現は、正確には「OpenAPI仕様に沿って書き、Swaggerのツールで扱う」という意味になります。会話の中では区別されないことが多いものの、調べ物をする際にはこの違いを理解していると効率が上がります。

名称が2つある経緯

歴史的な事情によるものです。もともとSwagger仕様として開発されていたものが、2015年にSmartBear社からOpenAPI Initiativeへ寄贈され、OpenAPI仕様として再出発しました。

OpenAPI Initiativeは、Linux Foundationの下にあるオープンガバナンス組織です。特定のベンダーに依存しない記述形式をつくり、発展させることを目的としています。

この経緯があるため、Swagger 2.0という古い仕様のバージョンも今なお現役で使われています。既存システムの仕様書がSwagger 2.0で書かれているというケースは珍しくありません。

バージョンの現状

仕様は継続的に更新されています。実務で目にするのは主に次の3系統です。

• Swagger 2.0：旧仕様。既存システムでまだ使われている
• OAS 3.0系：広く普及している。対応ツールが最も多い
• OAS 3.1系以降：JSON Schemaとの互換性が向上。webhooksが追加された

新規に書き始めるなら3.0系か3.1系を選びます。使用するツールがどのバージョンに対応しているかを先に確認してください。最新の状況はOpenAPI Initiative公式サイトで確認できます。

仕様書の1行目に記述するopenapiフィールドで、どのバージョンに準拠しているかを宣言します。ここを合わせないとツールが読み込めません。

OpenAPIでAPI仕様書を書く利点

ExcelやWordで書く方法と比べて、何が変わるのかを整理します。

人と機械の両方が読める

最も本質的な違いです。決められた構造に沿って書くため、プログラムが内容を解釈できます。ソースコードに直接アクセスしなくても、APIの機能を把握できる状態になります。

Excelの表も人は読めますが、機械には解釈できません。そのため、そこから何かを自動生成することができず、仕様書は読み物にとどまります。

機械が読めるということは、検証、生成、変換ができるということです。この違いが、後に挙げるすべての利点につながります。

閲覧用のドキュメントが自動生成される

定義ファイルを読み込ませるだけで、整形されたHTMLのドキュメントが生成されます。エンドポイントごとに折りたたまれた一覧が表示され、パラメータやレスポンスの形式が確認できます。

さらに、画面上から実際にAPIを呼び出して結果を確認できる機能もあります。利用者が動作を試しながら理解できるため、問い合わせの数が減ります。

見た目を整える作業から解放されるという効果も大きいところです。書式やレイアウトに時間を使わず、中身の記述に集中できます。

コードやモックを生成できる

定義ファイルから、クライアント側のコード、サーバー側のスタブ、モックサーバーを生成できます。多くの言語に対応したツールが公開されています。

特に効果が出るのがモックサーバーです。サーバー側の実装が完成する前に、定義ファイルだけでフロントエンド側の開発を進められます。待ち時間を減らせるという点で、並行開発と相性が良い方法です。

テストの生成にも使えます。定義に沿ったリクエストを送り、レスポンスが定義どおりかを検証する。この仕組みを組み込むと、実装のずれを自動で検出できます。

仕様書とコードのずれを防げる

手書きの仕様書で最も多い問題が、実装が変わったのに文書が更新されないという状態です。時間が経つほど、仕様書は信用できなくなります。

OpenAPIであれば、定義ファイルを検証の基準として使えます。実装が定義から外れたときに、テストで検出できる状態を作れます。

仕様書を「正」として運用できるという点が、他の形式との決定的な違いです。文書が実態から乖離していく問題に、構造的な対策を打てます。

OpenAPI仕様書の基本構造

書式はYAMLまたはJSONです。実務ではYAMLが多く使われます。記述量が少なく、コメントを書ける点が理由です。

トップレベルの主要オブジェクト

ファイルの最上位に置くのは、次の7つが中心になります。

openapi:    # 準拠する仕様のバージョン

info:       # APIの基本情報（タイトル、バージョン、説明）

servers:    # APIが動作するサーバーのURL

tags:       # エンドポイントを分類するためのタグ

paths:      # エンドポイントごとの定義（本体）

security:   # 全体に適用する認証方式

components: # 再利用する定義（スキーマ、認証方式など）

中心になるのはpathsとcomponentsです。pathsに個々のエンドポイントを書き、繰り返し使う定義をcomponentsに切り出すという構成になります。

必須になる項目

全部を書く必要はありません。openapiとinfoは必須で、加えてpaths、components、webhooksのうち少なくとも1つが必要です。

つまり、バージョン宣言と基本情報、そしてエンドポイントの定義さえあれば、仕様書として成立します。まず最小限で動かしてから、項目を足していくのが挫折しない進め方です。

なお、必須項目の細部は仕様のバージョンによって差があります。正確な定義はOpenAPI Specification（公式）で確認してください。

pathsの書き方

エンドポイントのパスをキーにし、その下にHTTPメソッドを置くという入れ子の構造です。1つのメソッドが1つの操作に対応します。

各操作の中には、概要、パラメータ、リクエストボディ、レスポンスを記述します。レスポンスはステータスコードごとに分けて書きます。

正常系だけでなく、エラー時のレスポンスも定義します。400や404、500のときにどういう形式が返るかが書かれていないと、利用者は実装できません。

componentsで共通化する

同じ定義を複数の箇所で使う場合、componentsに切り出して参照します。参照にはドル記号で始まるrefという記法を使います。

対象になるのは、レスポンスに含まれるデータの構造、共通のパラメータ、エラーレスポンス、認証方式などです。ユーザー情報のスキーマを1か所に定義し、複数のエンドポイントから参照するという使い方が典型です。

共通化しておくと、変更が1か所で済みます。項目を1つ追加する際に、すべてのエンドポイントを修正して回るという事態を防げます。

最小構成のサンプル

実際に書いてみると理解が進みます。まずは動く最小限から始めます。

動く最小限のYAML

ユーザー一覧を取得するAPIを1本だけ定義した例です。これだけでSwagger UIに読み込ませることができます。

openapi: 3.0.3

info:

  title: ユーザー管理API

  version: 1.0.0

  description: ユーザー情報を管理するAPIです。

servers:

  – url: https://api.example.com/v1

    description: 本番環境

paths:

  /users:

    get:

      summary: ユーザー一覧を取得する

      responses:

        ‘200’:

          description: 取得に成功

この段階でエディタに貼り付けて、表示を確認してみてください。動くものが見えると、以降の作業が進めやすくなります。

パラメータとレスポンスを足す

次に、絞り込み用のクエリパラメータと、返却されるデータの構造を追加します。

    get:

      summary: ユーザー一覧を取得する

      parameters:

        – name: status

          in: query

          description: 絞り込む状態

          required: false

          schema:

            type: string

            enum: [active, inactive]

      responses:

        ‘200’:

          description: 取得に成功

          content:

            application/json:

              schema:

                type: array

                items:

                  $ref: ‘#/components/schemas/User’

選択肢が決まっている項目はenumで列挙します。取り得る値が明示されるため、利用者が推測する必要がなくなります。

スキーマを切り出す

参照先のスキーマをcomponentsに定義します。ここに書いたものは、他のエンドポイントからも参照できます。

components:

  schemas:

    User:

      type: object

      required: [id, name]

      properties:

        id:

          type: integer

          example: 1001

        name:

          type: string

          example: 山田太郎

        status:

          type: string

          enum: [active, inactive]

exampleを書いておくと、ドキュメント上に実例が表示されます。型だけを見るより理解が速くなり、モックサーバーの応答にも使われます。

API設計や開発の進め方からご相談いただけます 書き方は分かっても、自社のAPIをどう設計するかは別の問題です。 要件の整理からご一緒する30分の無料相談をご用意しています。 ▶ 相談予約はこちら ※オンライン完結／秘密厳守／助成金活用のご相談も歓迎

Swagger関連ツールの使い分け

Swaggerという名前で提供されているツールは複数あります。それぞれ役割が違うため、目的に応じて選びます。

Swagger Editor｜書くためのエディタ

定義ファイルを記述するためのエディタです。ブラウザ上で使えるものが公開されており、インストールなしで試せます。

左側に記述欄、右側にプレビューが並ぶ構成で、書きながら表示を確認できます。文法の誤りもその場で指摘されるため、学習の段階では特に有用です。

エディタの拡張機能を使う方法もあります。手元のエディタにOpenAPI用の拡張を入れると、プレビューと補完が使えるようになります。

Swagger UI｜閲覧用の画面を生成する

定義ファイルから、対話的なHTMLドキュメントを生成するツールです。API利用者に公開する画面として使われます。

エンドポイントの一覧が表示され、クリックすると詳細が展開されます。画面上から実際にリクエストを送って応答を確認する機能もあります。

社内APIの利用者向けにこの画面を用意しておくと、問い合わせが大きく減ります。文書を送るより、URLを共有するほうが確実です。

Swagger Codegen｜コードを生成する

定義ファイルから、クライアントのライブラリやサーバーのスタブを生成するツールです。多くの言語に対応しています。

APIを呼び出す側のコードを手で書く必要がなくなり、定義の変更にも追随できます。複数の言語からAPIを利用する場合に効果が大きくなります。

生成されたコードをそのまま本番で使うかは判断が必要です。生成物を手で修正すると、次回の生成で上書きされます。手を入れる範囲を分離する設計にしておきます。

周辺ツール

Swaggerという名前が付いていないものも含めて、実務でよく組み合わせるツールがあります。

• Lintツール：記述の表記ゆれや必須項目の抜けを機械的に検出する
• モックサーバー：定義ファイルから、応答を返すだけのサーバーを起動する
• ドキュメント生成：Swagger UIとは異なる見た目のドキュメントを出力する
• フレームワークの連携機能：ソースコードから定義ファイルを生成する

最初からすべてを導入する必要はありません。エディタとUIから始め、運用が回り始めてからLintや自動生成を足していくのが現実的です。

作成の進め方

定義ファイルをいつ、誰が作るか。この選択が開発の進め方そのものを左右します。

デザインファーストとコードファースト

アプローチは大きく2つに分かれます。

• デザインファースト：先に定義ファイルを書き、それをもとに実装する
• コードファースト：先に実装し、コードの注釈から定義ファイルを生成する

デザインファーストでは、実装前に関係者で仕様を合意できます。フロントエンドとバックエンドが並行して着手でき、手戻りが減るという利点があります。

コードファーストは、既存システムに後から仕様書を用意する場合や、実装の変化が速い段階で有効です。コードと定義が自動的に一致する点が強みになります。

どちらを選ぶか

複数のチームや会社がAPIを介して連携するなら、デザインファーストが向いています。仕様が先に固まらないと、相手側が着手できないためです。

一方、単一チームで内部向けのAPIを作る場合は、コードファーストのほうが手間が少なく済みます。定義を二重管理しなくてよいためです。

判断軸は、仕様の合意が先に必要かどうかです。外部に公開するAPIや、契約に関わるインターフェースであれば、デザインファーストを選びます。

ファイルを分割する

エンドポイントが増えると、1つのファイルでは扱いきれなくなります。参照の記法を使って、複数のファイルに分割できます。

エンドポイントごとにファイルを分ける、スキーマを別ファイルにまとめるといった構成が一般的です。1つのファイルが数千行になる前に分割を検討します。

分割すると、複数人が同時に編集してもぶつかりにくくなります。バージョン管理システムでの差分も追いやすくなります。

運用で押さえること

書き始めるより、書き続けるほうが難しいというのがこの種の文書の実情です。

バージョン管理とレビュー

定義ファイルはテキストであるため、ソースコードと同じリポジトリで管理できます。これが大きな利点です。

変更は差分として確認でき、レビューの対象にできます。実装の変更と定義の変更を同じ単位で提出させれば、更新漏れを防げます。

API仕様の変更をレビュー必須にするというルールが有効です。エンドポイントの追加や項目の変更は、利用者への影響が大きいためです。

Lintで表記を揃える

複数人で書くと、記述の粒度や命名が揃わなくなります。機械的にチェックできるルールは、Lintツールに任せます。

説明文が書かれているか、エンドポイント名の命名規則に沿っているか、必須項目が埋まっているか。こうした確認を自動化できます。

自動チェックの仕組みに組み込むと、指摘が人の手を離れます。レビューでは、機械が判定できない設計の妥当性に集中できます。

説明文を省略しない

型と項目名だけでは、利用者は理解できません。descriptionに何を書くかで、仕様書の価値が決まります。

書くべきは、その項目が何を表すか、どういう場合に必須になるか、値の範囲や制約、業務上の意味です。「ユーザーID」とだけ書かれていても、情報は増えていません。

エラーレスポンスの説明は特に重要です。どういう条件でそのエラーが返るのかが書かれていないと、利用者は総当たりで確認することになります。

つまずきやすい点と対処

導入後に直面する問題を整理します。多くは運用ルールで防げます。

仕様書とコードがずれる

デザインファーストで進めた場合に起こります。実装の都合で仕様を変えたが、定義ファイルを直していないという状態です。

対策は、定義ファイルを基準にした自動テストを組み込むことです。実装のレスポンスが定義と一致するかを検証すれば、ずれた時点で検出されます。

変更の順序をルールにするという方法もあります。定義ファイルを先に更新し、レビューを通してから実装するという流れを徹底します。

認証の記述で迷う

セキュリティスキームの記述は、初学者がつまずきやすい部分です。componentsに認証方式を定義し、securityで適用するという2段構えになっています。

APIキー、Bearerトークン、OAuth2など、方式ごとに書き方が決まっています。自社で使っている方式に該当するものを、公式仕様で確認してから書きます。

エンドポイントごとに異なる認証を設定することもできます。認証不要のエンドポイントには、空の設定を明示的に書きます。

バージョン間の違いに戸惑う

ネット上の情報には、Swagger 2.0を前提としたものと、OAS 3.x を前提としたものが混在しています。書き方が異なる箇所があるため、そのまま真似すると動きません。

特に違うのが、リクエストボディの記述方法とコンポーネントの構造です。参照する記事がどのバージョンを扱っているかを確認する習慣をつけます。

迷ったら公式仕様を見るのが最も確実です。バージョンごとに文書が分かれて公開されています。

納品物としての扱いを決めていない

外部に開発を委託している場合の論点です。定義ファイルが納品対象に含まれているかを、契約段階で確認しておきます。

生成されたHTMLのドキュメントだけを受け取っても、後から更新できません。元になる定義ファイルそのものを受け取る必要があります。

IPAが公開する情報システム・モデル取引・契約書（第二版）は、ユーザ企業とITベンダのいずれにもメリットが偏らない中立的な契約書を目指して作成されたものです。成果物の範囲を整理する際の参考になります。

委託時の進め方や役割分担についてはシステム開発の外注とは｜メリット・デメリット、費用相場、外注先の種類と選び方でも整理しています。

まとめ

OpenAPIはHTTP APIを記述するための標準仕様、Swaggerはそれを扱うツール群です。旧Swagger仕様が寄贈されてOpenAPI仕様になったという経緯から、2つの名前が併存しています。

書式はYAMLまたはJSONで、必須となるのはopenapiとinfo、そしてpathsなどの定義です。最小構成から始めて項目を足していくのが、挫折しない進め方になります。

この形式で書く最大の価値は、機械が読めることです。ドキュメント、クライアントコード、モックサーバー、テストがすべて1つの定義から生成できます。

運用では、ソースコードと同じリポジトリで管理し、変更をレビュー対象にすることが要点です。あわせて、定義とコードのずれを検出する仕組みを組み込みます。

まずはエンドポイント1本だけの定義を書き、Swagger UIで表示させてみてください。10分ほどで、この形式の利点が体感できるはずです。

システム開発の進め方から、無料で相談できます 外部システムとの連携を検討している、社内に開発の知見がなく不安があるといった段階のご相談も承っています。 営業色は一切ありません。 ▶ 相談予約はこちら ※オンライン完結／秘密厳守／助成金活用のご相談も歓迎