Zenn
📑

OpenAPI SwaggerでAPI仕様書を作成

2025/02/18に公開
OpenAPI
tech

今回はOpenAPI Swaggerを用いたAPI仕様書作成について、ご紹介させていただきます。

はじめに

OpenAPIとは

REST APIのインターフェースを記述フォーマットで、フォーマットに沿った記述をすることでAPIのエンドポイント、パラメータ、レスポンス等を文書化することができます。記述方法は後述します。

Swaggerとは

OpenAPI仕様で作られたオープンソースで、ツールは主に下記があります。

ツール 概要
Swagger Editor OpenAPIの仕様を記述できるブラウザベースのエディタ
Swagger UI OpenAPIの仕様を動的なAPIドキュメントとしてレンダリングするツール
Swagger Codegen OpenAPI仕様からサーバースタブとクライアントライブラリを生成するツール

今回はブラウザベースで視覚化して作業したいので、VScodeの拡張機能でSwagger Editorをインストールします。

API仕様書作成手順

  1. 各種ymlファイルを記述（今回はAPIエンドポイントを纏めたbase.ymlと派生した3ファイルを準備）
  2. VS Codeの拡張機能OpenAPI (Swagger) Editorにてプレビュー
  3. OpenAPIソースをhtmlファイルに書き出し

ディレクトリ構成

OpenAPIの仕様について、1ファイルに纏め書きが可能ですが今回は下記の構成で作成していきます。

├── api
│   └──  (各種APIごとのディレクトリ)
│      ├── index.yml  # API基本情報
│      ├── query.yml # クエリパラメータ
│      └── response.yml # 200レスポンスの返却内容
├── index.html # ymlファイルの内容を元に生成
└── base.yml # 全てのAPIエンドポイントを纏め

ファイル記述

base.yml

こちらのファイルにはドキュメントの大元の役割を担ってもらってます。

base.yml
openapi: 3.1.0 # OpenAPIのバージョン指定

info: # APIの基本情報(タイトル、説明、バージョン等)を記述
  title: OpenAPI仕様書サンプル
  version: 1.0.0
  description: OpenAPIによるAPI仕様書サンプルです。
  license:
    url: http://localhost:8000

servers: # APIがホストとするサーバーを記述
  - url: "http://localhost:8000"
    description: 内部の API Server 本体（仮）

paths: # APIドキュメントのエンドポイント
  /api/search:
    $ref: api/search/index.yml
  /api/detail:
    $ref: api/detail/index.yml
  /api/store:
    $ref: api/store/index.yml

今回はpaths内にapiエンドポイントごとにindex.ymlファイルを設定していきます。

index.yml

1つのAPIエンドポイントのテンプレートファイル。リクエストパラメータはquery.ymlを参照し、レスポンス200正常系の際の詳細レスポンスの参照先としています。
以下サンプルコードになります。

get: #APIエンドポイントに応じてpost,put等を指定
  operationId: search #メソッド名
  summary: 検索画面 #簡易的なAPI説明
  description: サンプルデータを検索するAPI #APIの詳細な説明
  parameters: #クエリパラメータ
    $ref: "./query.yml"
  responses: #レスポンス
    "200":
      description: OK
      content:
        application/json:
          schema:
            $ref: response.yml
    "400":
      description: Bad Request
    "404":
      description: Not Found
    "500":
      description: Internal Server Error

query.yml

こちらは名前の通り、APIに必要なクエリパラメータを記述します。

- name: id #パラメータ名
  in: query #クエリパラメータならquery、パスパラメータならpath
  description: id #クエリの説明
  schema:
    type: intger #クエリの型
    example: 1 #サンプル値
- name: type
  in: query
  description: タイプ
  schema:
    type: array
    items:
      type: string
    example: ['normal', 'error']
- name: date
  in: query
  description: 日付
  schema:
    type: date
    example: '2024-10-01'

response.yml

レスポンス200正常系の返却値の詳細を記述します。
typeで返却の型を指定していくのがポイントです。

type: object
properties: 
  success:
    title: 判定
    description:
    example: true
  data:
    title: 結果
    description: 
    type: object
    properties:
      results:
        type: array
        items:
          type: object
          properties:
            id:
              title: id
              type: integer
              example: 11
	  type:
              title: タイプ
              type: string
              example: 'normal'
	  date:
              title: 日付
              type: date
              example: '2024-10-01'

OpenAPI (Swagger) Editorでプレビュー

これでymlファイルは記述が終わりましたので問題ないか、先ほどインストールしたVScodeの拡張機能で確認します。
ブラウザベースの視覚化は[Shift] + [alt] + p（Macは[Command] + [Shift] + p）で可能です。

先ほど記述した/api/searchの記述の中身も問題ないか確認します。

HTMLファイルに書き出し

最後に記述したOpenAPIソースをhtmlファイルに書き出していきます。
今回API書き出しのためにnpmのredocly/cliを使用していきます。※npmとnodeがグローバルインストールされている必要があります。

npm install -g @redocly/cli

インストールができましたら、base.ymlが存在するディレクトリで下記コマンドを実行してhtmlファイルの書き出しを行います。

redocly build-docs base.yml --output index.html

無事コマンドが実行出来ましたら下記が表示されます。

それでは書き出ししたhtmlファイルを確認しましょう。

まとめ

このように簡単な記法だけでAPI仕様書を作成することができます。
今回は役割ごとにファイルを分けて仕様書を作成しましたが、前述通りbase.ymlファイル等に記法守って纏めて書き出すことも可能です。
手元にVScodeと拡張機能を入れるだけでOpenAPIに記述確認はできるので是非試してみてください。

参考文献

https://zenn.dev/knm/articles/32106f623bd382

Discussion