Swaggerについて書かれているサイトやブログは多く見られるが、OpenAPIのバージョンの違いが理解の障害になると感じたので、備忘録として記事に起こした。
表：OpenAPI2.0とOpenAPI3.0の構造の違いを簡略に
| OpenAPI 2.0 | OpenAPI 3.0 | 必須 | 役割 |
|---|---|---|---|
| openapi | openapi | ◯ | OpenAPIのセマンティックのバージョン |
| info | info | ◯ | メタデータ |
| security | security | API全体で使用できるセキュリティメカニズの宣言(認証と承認などの) | |
| host,basePath,schemes | hosts | APIを提供するホスト | |
| paths,produces,consumes | paths | ◯ | APIで使用可能なパスと操作 |
| tags | tags | パスごとのタグによるグループ化 | |
| externalDocs | externalDocs | 追加の外部ドキュメント | |
| definitions,parameters,responses | components | 仕様のさまざまなスキーマを保持する要素 |
上記の表から見て分かる通り、2.0と3.0の大きな違いは構造の違いです。2.0で細分化されていたそれぞれのフィールドがわかりやすくまとめられている。
次の章で、それぞれの細かな違いと2.0で書かれている記事を3.0で書くための変更について確認する。
それぞれの細かなと基本的な構文
openapi (必須)
openapiではOpenAPIのバージョンを"セマンティックバージョニング(SemVer)"で指定する構文である。
v2.0ではOpenAPIに統合される前なので、swaggerと記載している。
※記事の記載時点での最新Vesionは3.0.3である。
# OpenAPI 2.0
swagger: 2.0
# OpenAPI 3.0
openapi: 3.0.3
#3.0.0 ~ 3.0.nの間であればOK
info (必須)
infoでは、APIに関するメタデータを記載する。バージョンの違いによる大きな差はない。
必須なフィールドは、titleとversionの２つがある。
versionではSemVerで表記するのがメジャーであるが、クォテーション"" ''で囲うと
文字列として扱われるので自由な形式でバージョン指定ができる。
# sample 01
info:
#APIの名前
title: sample 01 API
#APIのバージョン
version: 1.0.0
# sample 02
info:
title: sample 02 AIP
version: "破壊的な変更 v1"
security
認証や承認で用いられるsecurityは、v3.0で使用できる認証タイプがかなり増えた。
- HTTP認証
- Basic
- Bearer (NEW)
- Other (NEW)
- API Keys
- OAuth 2
- OpenId Connect Discovery (NEW)
構文としての違いもかなり確認される。主な変更として
-
securityDefinitionsがComponents内にsecuritySchemesとして記述する場所とフィールド名が異なる。 - HTTP認証の種類が増えたため、typeが
basicからhttpへ変更 - APIキーとしてクッキーを送信できるようになった。
# OpenAPI 2.0
securityDefinitions:
BasicAuth:
type: basic
# ...
# OpenAPI 3.0
Components:
securitySchemes:
bearerAuth:
type: http
# ...
認証についての詳細は別の記事にて
paths (必須)
pathsでは、APIのエンドポイントであるパスを記載する。
pathsがAPIの基幹となっています。基本的にpathsに全て書き込むのではなく、重複するような内容はcomponentsに記載することが多い。
paths:
/ping:
get:
responses:
'200':
description: OK
content:
text/plain:
schema:
type: string
example: pong
以上を踏まえた最小構成
以下の最小構成を参照しながら、versionの違いを埋めていくようにv2.0の資料を参考にするとerrorを吐かれずに正しく書けるはず
openapi: '3.0.0'
info:
title: sample api
version: 0.0.1
paths: {}
完全に理解してない単語まとめ
- セマンティックバージョニング(Semantic Versioning/SemVer)
３つの数字で表現されるよく見るバージョン管理記法。バージョンナンバーとしてX.Y.Zという形式に区切られ
Xはメジャーバージョン、Yはマイナーバージョン、Zはパッチバージョンを表す。
さらに詳しいバージョン管理に関する規約はこちら⇨セマンティックバージョンニング2.0.0