OpenAPIの記法についてのまとめ
こんにちは。
PHR事業開発部の村越です。
今回は、業務で使用しているOpenAPIの記法についてまとめようかと思います。
OpenAPIとは？
OpenAPIとは、RESTful APIを記述する際のフォーマットになります。
OpenAPIはYAMLファイルで記載され、そこからドキュメントやAPI Clientの自動生成が可能です。
記法
OpenAPIの基本構造は下記になります。
openapi: 3.0.0
info:
# APIに関する情報を記載する
servers:
# APIのURLを記載する
paths:
# APIのエンドポイントを記載する
components:
# APIで使用するオブジェクトスキーマを記載する
tags:
# APIで使用されるタグのリストを記載するそれぞれについて詳細に記載します。
info
info:
# タイトル：必須
title: TEST API
# 説明
description: テスト用APIです。
# 利用規約
termsOfService: http://example.com/terms/
# コンタクト用の情報（サポートのURL、メールアドレス）
contact:
name: APIサポート
url: http://www.example.com/support
email: support@example.com
# ライセンス情報
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
# APIドキュメントのバージョン：必須
version: 1.0.0servers
servers:
# 本番、ステージングなど、複数の記載が可能
# サーバーのURL：必須
- url: https://api.test-server.com/v1
# サーバーの説明
description: 本番サーバー
- url: https://stg.test-server.com/v1
description: ステージングサーバーpaths
基本的な構造は以下のようになります。
paths:
# APIのエンドポイント。複数記載可能
/users:
# HTTPメソッド（GET, PUT, POST, DELETE, OPTIONS, DELETE, PATCH, TRACEが使用可能）
get: # GET
# 最初に記載したtagsのどれに当たるかを記載する
tags:
- user
# APIの概要
summary: ユーザー取得
# APIの説明
description: 全ユーザーを取得して返却する
# レスポンスの定義
responses:
# HTTP ステータス
'200':
# 説明
description: successful operation
# レスポンスを記載
content:
# レスポンスの形式を指定
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User' # 参照するモデル
example: # サンプルデータ
- id: 1
name: のぼり始
- id: 2
name: のぼり益代
post: # POST
tags:
- users
summary: ユーザー作成
description: ユーザーを新規に作成する
# リクエストボディ
requestBody:
description: 作成するユーザーの情報
content:
application/json:
schema:
$ref: '#/components/schemas/User'
example:
id: 3
name: のぼり新
responses:
'200':
description: successful operation上記の/usersのように、APIの定義を複数記載します。
途中に出てくる $ref は Components Object というもので、components配下で定義したオブジェクトスキーマを呼び出しています。
こちらの記載は後ほど紹介します。
URLにパラメータが付与されている場合の記載は以下になります。
paths:
/users/{userId}:
get:
tags:
- users
summary: ユーザー検索.
description: 指定したユーザーの情報を返却する
# リクエストパラメータ
parameters:
- name: userId # パスで指定した値を記載
in: path # パラメータをパス内に含める
description: ユーザーID
required: true
schema:
type: integer
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: object
items:
$ref: '#/components/schemas/User'
example:
id: 1
name: のぼり始上記のように、パス内に{XXXX}の形式でパラメータを記載し、parameters内で形式などを指定します。
パス内に含める場合は、in に path を指定しますが、headerやqueryを指定することで、それぞれヘッダー、クエリに指定したパラメータを付与することが出来ます。
parameters:
- name: token
in: header
description: トークン
required: true
schema:
type: string
- name: query
in: query
description: 検索したい文字列
required: true
schema:
type: stringcomponents
components:
# スキーマオブジェクトの定義
schemas:
# モデル名
User:
# 型
type: object
# 必須プロパティ
required:
- id
# プロパティ
properties:
# プロパティ名
id:
# 型
type: integer
# フォーマット
format: int64
name:
type: string上記は、pathsで記載した User の定義になります。
Userのようなモデルは、components→schemasの下に定義を記載します。
componentsにはschemasの他に
requestBodies、responses、parameters
などを記載することが出来ます。
paths:
/users:
post:
tags:
- users
summary: ユーザー作成
description: ユーザーを新規に作成する
requestBody:
$ref: '#/components/requestBodies/ReqUser'
responses:
'200':
description: successful operation
/users/{userId}:
get:
tags:
- users
summary: ユーザー検索.
description: 指定したユーザーの情報を返却する
parameters:
- $ref: '#/components/parameters/UserId'
responses:
'200':
$ref: '#/components/responses/success'
components:
parameters:
UserId:
in: path
description: ユーザーID
required: true
schema:
type: integer
requestBodies:
ReqUser:
description: 作成するユーザーの情報
content:
application/json:
schema:
$ref: '#/components/schemas/User'
example:
id: 3
name: のぼり新
responses:
success:
description: successful operation
content:
application/json:
schema:
type: object
items:
$ref: '#/components/schemas/User'
example:
id: 1
name: のぼり始
schemas:
User:
type: object
required:
- id
properties:
id:
type: integer
format: int64
name:
type: stringtags
tags:
# タグ名：必須
- name: users
# タグの説明
description: ユーザーに関する操作最後に
今回はOpenAPIの記法についてまとめてみました。
OpenAPIは今まで使ったことがなく、慣れるまでは時間がかかり面倒だなと思うこともあったのですが、慣れてしまえばドキュメントが簡単に記載でき、API Clientの自動作成もしてくれるのでとても楽になると思います。
今回は以上となります。
今後とも「PSP」をよろしくお願い致します。
村越