Go to Qiita Advent Calendar Top
LoginSignup
7
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Day 22

NTTテクノクロス Advent Calendar 2025

@CorydorasNomu(shunn nomu)

そろそろOpenAPI (Swagger) で仕様書を書こう

Last updated at Posted at 2025-12-21

はじめに

こんにちは。NTTテクノクロスの野村（@CorydorasNomu）です。この記事はNTTテクノクロスAdvent Calendar 2025（シリーズ1）の22日目の記事になります。
サーバ・クライアント間で通信をするウェブアプリケーション開発の現場では、メンバー間で API 仕様を早く正確に共有することが重要です。そこで注目されるのが OpenAPI (Swagger) です。今この記事を読んでいる皆さんは、「何を今さら、そんなこと誰でも知っているし使ってるよ」と思われるかもしれません。はい、筆者もそう思っています。しかし最近気づいたのですが、どうやらそうでもないらしい。
なので本記事では OpenAPI (Swagger) を活用することで、どのような恩恵を得られるのかについて解説します。本記事がプロジェクトへの OpenAPI (Swagger) 導入の契機になれば嬉しいです。

OpenAPI (Swagger) とは

OpenAPI とは、OpenAPI Initiative という団体が策定・管理する API 仕様書のフォーマット（標準仕様）で、yaml または json で記述できます。そして Swagger は、この標準仕様でドキュメントを作成・管理するためのツール群です。

OpenAPI (Swagger) を始める

Visual Studio Code に拡張機能を導入すればすぐに作業を始められます。Visual Studio Code を使っていない方は、公式ページで提供されているWebエディタでも作業が可能です。
今回は最小限の構成で OpenAPI (Swagger) ドキュメントの運用を始められるようにテンプレートを作成しました。これをコピペをしてドキュメントの基礎を作成し、公式ページのサンプルを参考にしながら、プロジェクトに合わせて追加や修正をしていただければと思います。今回は yaml 形式で書きます。

OpenAPI (Swagger) のテンプレート 
openapi: 3.0.4
info:
  title: はじめての OpenAPI (Swagger) どきゅめんと
  description:
    OpenAPI (Swagger) を使って API 仕様書を作成する時のテンプレートです。
  version: 1.0.0

# デプロイ環境のエンドポイントのベースURL
servers:
  - url: https://my-bookstore-service/dev
    description: 開発環境

# API Endpoint のタグ付け
tags:
  - name: book
    description: 書籍情報管理API

#　=========================================　#
#   API Endpoint 定義
#　=========================================　#
paths:
  /books:
    post:
      tags:
        - book
      summary: 書籍情報登録
      description: 書籍情報をデータベースに登録する。
      operationId: registerBook
      # リクエストの詳細
      requestBody:
        description: 書籍情報の登録情報
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterBookRequest'
        required: true
      # レスポンスの詳細
      responses:
        '204':
          description: 成功
        '400':
          description: 不正なリクエスト
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: 'リクエストボディの形式が不正です。'
        '403':
          description: 登録権限なし
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: 'この操作を実行する権限がありません。'
        '500':
          description: システムエラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: 'システムエラーが発生しました。'
    get:
      tags:
        - book
      summary: 書籍情報一覧取得
      description: データベースから書籍情報一覧を取得する。
      operationId: fetchBookList
      # レスポンスの詳細
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/fetchBookListResponse'
        '500':
          description: システムエラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: 'システムエラーが発生しました。'
  /books/{bookId}:
    get:
      tags:
        - book
      summary: 書籍情報取得
      description: データベースから書籍情報を取得する。
      operationId: fetchBook
      # パスパラメータの詳細
      parameters:
        - name: bookId
          in: path
          description: 書籍ID（ISBN）
          required: true
          schema:
            type: string
            example: '9784003900024'
      # レスポンスの詳細
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/fetchBookInfoResponse'
        '404':
          description: 書籍情報が見つからない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: '指定された書籍情報が見つかりません。'
        '500':
          description: システムエラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: 'システムエラーが発生しました。'
    put:
      tags:
        - book
      summary: 書籍情報更新
      description: データベースの書籍情報を更新する。
      operationId: updateBook
      # パスパラメータの詳細
      parameters:
        - name: bookId
          in: path
          description: 書籍ID（ISBN）
          required: true
          schema:
            type: string
            example: '9784003900024'
      # リクエストの詳細
      requestBody:
        description: 書籍情報の更新情報
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterBookRequest'
        required: true
      # レスポンスの詳細
      responses:
        '204':
          description: 成功
        '400':
          description: 不正なリクエスト
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: 'リクエストボディの形式が不正です。'
        '403':
          description: 更新権限なし
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: 'この操作を実行する権限がありません。'
        '404':
          description: 書籍情報が見つからない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: '指定された書籍情報が見つかりません。'
        '500':
          description: システムエラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: 'システムエラーが発生しました。'
    delete:
      tags:
        - book
      summary: 書籍削除
      description: 書籍情報をデータベースから削除する。
      operationId: deleteBook
      # パスパラメータの詳細
      parameters:
        - name: bookId
          in: path
          description: 書籍ID（ISBN）
          required: true
          schema:
            type: string
            example: '9784003900024'
      # レスポンスの詳細
      responses:
        '204':
          description: 成功
        '403':
          description: 削除権限なし
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: 'この操作を実行する権限がありません。'
        '404':
          description: 書籍情報が見つからない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: '指定された書籍情報が見つかりません。'
        '500':
          description: システムエラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: 'システムエラーが発生しました。'

#=========================================#
#   データ構造 (Schema) 定義
#=========================================#
components:
  schemas:
    # 書籍情報登録リクエスト
    RegisterBookRequest:
      required:
        - isbn
      type: object
      properties:
        isbn:
          type: string
          description: 国際標準図書番号（ISBN）
          example: '9784003900024'
        title:
          type: string
          description: 書籍のタイトル
          example: '自由論'
        author:
          type: string
          description: 著者名
          example: 'J.S.ミル'
        publisher:
          type: string
          description: 出版社名
          example: '◯◯出版'
    # 書籍情報一覧
    fetchBookListResponse:
      type: array
      items:
        $ref: '#/components/schemas/fetchBookInfoResponse'
    # 書籍情報詳細
    fetchBookInfoResponse:
      type: object
      properties:
        isbn:
          type: string
          description: 国際標準図書番号（ISBN）
          example: '9784003900024'
        title:
          type: string
          description: 書籍のタイトル
          example: '自由論'
        author:
          type: string
          description: 著者名
          example: 'J.S.ミル'
        publisher:
          type: string
          description: 出版社名
          example: '◯◯出版'
        registeredAt:
          type: string
          format: date-time
          description: 書籍情報登録日時
          example: '2025-12-12T10:00:00Z'
    Error:
      type: object
      properties:
        message:
          type: string
          description: エラーメッセージ
          example: 'エラーが発生しました。'
  
  # セキュリティスキーム定義（必要に応じて追加）
  securitySchemes:
    bookstore_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT

上記をコピペした yaml ファイルを Visual Studio Code で開きプレビュー表示すると、以下のように見えるはずです。ちなみに yaml ファイルの中で、それぞれの階層のキーが何を意味しているのかといったお話については、こちらの記事が参考になります。

adventclendar_2025_01.png

Visual Studio Code でプレビュー表示の方法は以下のとおりです。

  • Windows なら Shift + alt + p
  • macOS なら Shift + option + p

なぜ OpenAPI (Swagger) なのか

Microsoft の Wordや Excel ではなく OpenAPI (Swagger) で API 仕様書を書くメリットには以下のようなものがあります。

バージョン管理やレビューが簡単

yaml や json はテキストベースのファイルなので、OpenAPI 形式の仕様書を Git で管理する場合、変更の履歴や内容差分の確認が容易になります。
コミットの履歴を見れば、仕様が変更された時期やその変更の意思決定をした責任者（マージをした人）を追跡できます。またチームで開発をしていると、変更を main ブランチにマージするとき、Pull Request を発行して必ずシニアエンジニアのレビューを必須にしたいことがあると思います。このときチームメンバに Git 操作のスキルがあれば、こうした運用の作業負担を減らすことができます。
その昔、API 仕様書を Word / Execl ファイルで管理していた時代は、変更部分だけを赤文字にしたり削除部分には取り消し線を引いたりするなどの修正をし、それをファイルサーバにアップロードして管理者が内容を確認した後、赤い字部分を黒文字に変更するという運用をしていたそうです。
人間の手による作業ではどうしても抜け・漏れが発生するので、こうした変更内容の管理はできるだけ機械的にして、作業の精度向上と省力化を進めたいですね。

モックサーバをすぐに起動できる

OpenAPI は機械可読なドキュメントの仕様です。なのでこれに準じて API 仕様書を作成すると、例えば Prism などのツールを使うことでモックサーバをカンタンに構築できます。具体的な使い方についてはこちらの記事が参考になります。
それでは先ほど示したサンプルを api_sample.yaml というファイル名で保存します。そして Visual Studio Code のターミナルで api_sample.yaml が保存されているフォルダに移動し、下記のコマンドを実行してみましょう。

# Prism をインストール
npm i -D @stoplight/prism-cli

# モックサーバを起動
npx prism mock ./api_sample.yaml

ターミナルに以下の内容が表示されたら、モックサーバの起動に成功です。なおリクエストのパスパラメータの bookId に設定されている値は、Prism が例として自動生成した文字列です。

mockserver_02.png

それでは起動したモックサーバに対してリクエストを飛ばしてみましょう。ターミナルあるいはコマンドプロンプトを新たに起動し、下記のコマンドを実行します。（curl のセットアップ手順は省略します）

# 書籍一覧を取得
curl -i http://localhost:4010/books

以下のように、モックサーバから書籍の一覧が返却されます。

mockserver_01.png

こうしたツールを使うことで、バックエンド側の作業の進捗に引きずられることなくフロントエンド側の開発を進められます。Word / Excel ファイルは内容が機械可読ではないので、上記のような作業効率化の恩恵を受けることができません。

ソースコードを直接生成できる

使用する機会が少ないですが、OpenAPI の形式で作成した API 仕様書からソースコードを直接生成することができます。ただし今回の方法で生成されるのは、飽くまで中身が空のサーバ実装です。業務ロジックなどは一切含まれないので、開発を素早く立ち上げるときに使う小技のようなイメージですね。
今回は openapi-generator-cli を使って実演してみましょう。先ほどと同じく api_sample.yaml が保存されているフォルダ階層で下記のコマンドを実行し、ツールをインストールします。

# openapi-generator-cli をインストール
npm install -D @openapitools/openapi-generator-cli

インストールが完了したら、続けて下記のコマンドを実行しコードを生成します。

npx openapi-generator-cli generate \
  -i ./api_sample.yaml \
  -g nodejs-express-server \
  -o ./generated-server
オプション 意味
-i ソースコードの生成元となるインプットファイル。
-g コードを生成するジェネレータ種別。
今回は TypeScript で Express の形式に準拠することにします。
-o 生成したソースコードが出力されるフォルダ。

処理が成功すると、api_sample.yaml ファイルが保存されているフォルダ内に -o オプションで指定した generated-server フォルダが自動で作成され、その下に生成されたソースコードが格納されます。

stubcode_01.png

繰り返しになりますが、こうしたツールを使った業務効率化も、機械可読である OpenAPI 形式に準拠して API 仕様書を作成しているからこそ可能になるものです。Word / Excel ファイルでドキュメントを運用しているプロジェクトでは、こうした生産性向上を図ることができません。

AI エージェントとの相性が良い

2025年は AI エージェント元年と言っても差し支えないと思いますが、OpenAPI 形式で API 仕様書を作成するメリットはここにも及びます。筆者が普段業務で使用している GitHub Copilot を使って実演をしてみましょう。
Visual Studio Code で GitHub Copilot と会話をするためのチャット画面を開き、以下の指示を与えてみます。

schema で定義されているデータモデル内の example を以下のように変更してください。

- isbn を 9784003362334 に変更
- title を社会契約論に変更
- author をルソーに変更

すると GitHub Copilot は自身で api_sample.yaml の内容を解析し、指示に応じた修正を実行してくれます。全部で変更部分は6箇所あるようです。変更前と変更後の差分を作業者（人間）の目で確認し、問題がなければ赤枠で示されている Keep をクリックして修正を確定させます。

aiagent_01.png

またファイルの直接修正だけでなく、作業内容のコミットやプッシュといった Git 操作についても、チャット画面から自然言語で指示を出すことができます。
今回の内容変更は簡単すぎましたが、実際のプロジェクトでは API エンドポイントや定義されるデータスキーマの数は膨大なものになります。そうなった時に、抜け漏れなく仕様書をメンテナンスしていくために AI エージェントは非常に有力な手段となります。

まとめ

このように、OpenAPI (Swagger) を使って API 仕様書を作成すると、開発において多くのメリットを享受することができ、生産性が向上します。Word / Excel でも AI がファイルの中身を自動で解析・修正は可能ですが、やはり Git やその他のツールなど外部のエコシステムと連携させるという点において、OpenAPI (Swagger) の強みが際立つように感じます。まだこうした手法を導入していないプロジェクトがありましたら、これからの設計あるいは開発業務での活用を前向きに検討してみてはいかがでしょうか。

7
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
7
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?