OpenAPI入門：YAML仕様の書き方からSwagger UIで確認するまで

OpenAPI
スポンサーリンク

OpenAPI入門：YAML仕様の書き方からSwagger UIで確認するまで

はじめに

APIを開発するとき、仕様をどうやって共有していますか？MarkdownでAPIドキュメントを書いてもすぐ古くなる、口頭で説明してすれ違いが起きる、といったことがよくあります。

OpenAPIはRESTful APIの仕様を標準フォーマットで記述することで、ドキュメントの自動生成やコードの自動生成ができる仕組みです。この記事ではOpenAPIの基本的な書き方から、Swagger UIで視覚的に確認するところまでを解説します。

OpenAPIとは

OpenAPI（旧称：Swagger）は、RESTful APIの仕様をYAMLまたはJSON形式で記述するための標準フォーマットです。エンドポイント・リクエスト・レスポンスをコードと同じリポジトリで管理できます。

現在のバージョンはOpenAPI 3.1です。

使うメリット - Swagger UIなどでAPIドキュメントを自動生成できる - フロントエンドとバックエンドで仕様を事前に合意できる - クライアントコードやサーバースタブを自動生成できる - 仕様とコードを同じリポジトリで管理できる

基本構造

OpenAPI仕様はいくつかのセクションで構成されています。

openapi: 3.1.0      # OpenAPIのバージョン
info:               # APIの基本情報
  title: My API
  version: 1.0.0
paths:              # エンドポイントの定義
  /users:
    get:
      ...
components:         # 共通で使うスキーマの定義
  schemas:
    ...

シンプルなAPI仕様を書いてみる

ユーザー一覧を返すAPIを例に書いてみます。

openapi: 3.1.0
info:
  title: User API
  version: 1.0.0

paths:
  /users:
    get:
      summary: ユーザー一覧を取得する
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

  /users/{id}:
    get:
      summary: ユーザーを1件取得する
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: 見つからない

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: 田中太郎
        email:
          type: string
          example: tanaka@example.com

ポイント解説

  • paths: エンドポイントのパスをキーにして定義する
  • parameters: パスパラメータやクエリパラメータを定義する（in: path / in: query）
  • responses: ステータスコードごとにレスポンスを定義する
  • $ref: 共通のスキーマを参照する（同じ定義の重複を避ける）
  • components/schemas: 使い回すスキーマをここにまとめる

リクエストボディを定義する

POSTやPUTなど、リクエストボディが必要な場合は requestBody で定義します。

  /users:
    post:
      summary: ユーザーを作成する
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - email
              properties:
                name:
                  type: string
                  example: 田中太郎
                email:
                  type: string
                  example: tanaka@example.com
      responses:
        '201':
          description: 作成成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

required に必須プロパティを列挙することで、バリデーションツールが未入力を検知できます。

Swagger UIで確認する

書いたOpenAPI仕様をSwagger UIで視覚的に確認できます。エンドポイントの一覧表示や、ブラウザ上からの試し打ちができます。

オンラインで確認する（インストール不要）

Swagger Editor にアクセスして、左側のエディタに書いたYAMLを貼り付けるだけです。右側にSwagger UIがリアルタイムで表示されます。

Dockerでローカル実行する

docker run -p 8080:8080 swaggerapi/swagger-ui

http://localhost:8080 にアクセスするとSwagger UIが起動します。

ローカルのYAMLファイルを読み込む場合は以下のように指定します。カレントディレクトリに openapi.yaml がある場合に使えます。

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

まとめ

  • OpenAPIはRESTful API仕様をYAML/JSONで記述する標準フォーマット（旧称：Swagger）
  • paths でエンドポイント、components/schemas で共通スキーマを定義する
  • $ref で同じスキーマを使い回して重複を避けられる
  • Swagger Editor（オンライン）やSwagger UI（Docker）で視覚的に確認できる

nullable・enum・共通化など詳細なスキーマ設定は「OpenAPIスキーマ設定チートシート：nullable・enum・共通化まで」を参照してください。

RailsでOpenAPIを活用したコントローラー実装については「RailsでOpenAPIを使ったコントローラー作成入門」を参照してください。