【Swagger】バージョンの違いから見るOpenAPIの最小構成

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)

構文としての違いもかなり確認される。主な変更として

1. securityDefinitionsがComponents内にsecuritySchemesとして記述する場所とフィールド名が異なる。
2. HTTP認証の種類が増えたため、typeがbasicからhttpへ変更
3. 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