OpenAPIとSwaggerの違いは何ですか？

Swaggerは元々SmartBear社が開発したAPIドキュメントのフォーマットです。2016年にOpenAPI Initiativeに寄贈され「OpenAPI仕様（OAS）」として標準化されました。現在「Swagger」はSwagger UIやSwagger Editorなどのツール群を指し、「OpenAPI」は仕様書の規格を指します。

OpenAPI仕様書はYAMLとJSONどちらで書くべきですか？

どちらでも仕様的に有効です。YAMLはコメントが書けて人間が読みやすく、JSONはプログラムで扱いやすいという特徴があります。チームの好みや既存ツールとの親和性で選択してください。多くのプロジェクトでYAMLが採用されています。

コードファーストとデザインファーストのどちらが良いですか？

新規API開発ではデザインファースト（先にOpenAPI仕様を書き、それからコードを実装）が推奨されます。仕様を先に固めることでフロントエンドとバックエンドが並行開発でき、設計の見直しコストが低い段階で問題を発見できます。

OpenAPI（Swagger）仕様書の書き方入門ガイド【2026年版】

OpenAPI仕様とは

OpenAPI仕様（OAS：OpenAPI Specification）は、RESTful APIを記述するための業界標準フォーマットです。APIのエンドポイント・リクエスト/レスポンスの構造・認証方式・エラーコードなどを、機械が読めるYAMLまたはJSON形式で記述します。OpenAPI仕様書があれば、Swagger UIなどのツールでインタラクティブなドキュメントを自動生成したり、クライアントSDKを自動生成したりすることができます。

現在の最新メジャーバージョンはOpenAPI 3.1です。本記事ではOpenAPI 3.0をベースに解説します。

OpenAPI仕様書の基本構造

OpenAPI仕様書（YAML形式）の基本構造は以下の通りです。

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: 成功

主要なセクションの解説

info セクション

APIの基本情報を記述します。title（API名）、version（バージョン）、description（説明）のほか、contact（連絡先）やlicense（ライセンス）も記述できます。

servers セクション

APIのベースURLを定義します。本番・ステージング・開発環境など複数のサーバーを列挙できます。Swagger UIで切り替えて試せるため、環境ごとに分けて記述することをお勧めします。

paths セクション

APIのエンドポイントとその操作を定義するメインセクションです。各パスに対してGET・POST・PUT・PATCH・DELETEのHTTPメソッドを定義します。各操作にはsummary（概要）、description（詳細説明）、parameters（パラメーター）、requestBody（リクエストボディ）、responses（レスポンス）を記述します。

components セクション

スキーマ・レスポンス・パラメーターなどの再利用可能な定義をまとめます。$refを使って他のセクションから参照することで、重複定義を避けて保守性を高められます。

スキーマ定義の書き方

components/schemasセクションでデータモデルを定義します。

components:
  schemas:
    User:
      type: object
      required:
        - id
        - name
        - email
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: 山田太郎
        email:
          type: string
          format: email
          example: yamada@example.com
        createdAt:
          type: string
          format: date-time

認証の定義

securitySchemesセクションで認証方式を定義し、各操作にsecurityを記述します。

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

Swagger UIで可視化する

OpenAPI仕様書を作成したら、Swagger UIを使ってブラウザ上でインタラクティブに表示・テストできます。DockerでSwagger UIを起動する場合は以下のコマンドを使います。

docker run -p 8080:8080 -e SWAGGER_JSON=/spec/openapi.yaml   -v $(pwd):/spec swaggerapi/swagger-ui

Swagger UIではAPIのエンドポイント一覧を確認でき、実際にリクエストを送ってレスポンスを確認するTry it out機能も使えます。

コードジェネレーターの活用

OpenAPI仕様書からクライアントSDKやサーバースタブを自動生成できます。openapi-generatorを使えば、TypeScript・Python・Go・Javaなど50以上の言語のクライアントコードを自動生成できます。型安全なAPIクライアントを手動で書く手間が省け、仕様変更時も再生成するだけで済みます。

デザインファーストでの活用

API開発において、まずOpenAPI仕様書を作成してからコードを実装する「デザインファースト」アプローチが効果的です。仕様書を先に作ることで、フロントエンドとバックエンドが仕様書を共通インターフェースとして並行開発できます。また、モックサーバー（Prism等）を使えば、バックエンドの実装を待たずにフロントエンドの開発を進めることも可能です。

OpenAPI仕様書の管理

OpenAPI仕様書はGitでバージョン管理し、APIの変更と同期して更新します。CIパイプラインでOpenAPIのバリデーション（構文チェック）を自動化することで、不整合な仕様書のマージを防ぎます。

まとめ

OpenAPI仕様は現代のAPI開発における事実上の標準です。仕様書を整備することで、ドキュメントの自動生成・SDK自動生成・モックサーバー・テストの自動化まで、開発プロセス全体の効率化につながります。新規APIプロジェクトでは最初からOpenAPI仕様書の作成を組み込むことをお勧めします。