OpenAPIを一から学ぶ ①
ほとんど公式ドキュメントの翻訳と要約です。
OpenAPIとは？
The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to HTTP APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.
筆者訳: OpenAPIは、サーバー開発言語に依存しない、標準的なHTTP APIのインタフェースを定義します。それらによって、人・コンピュータ双方が、ソースコードやドキュメント、ネットワーク通信を介さずに、サービスに何が出来るかを発見し理解することができます。
Swaggerとは違う?
Swaggerというのは、OpenAPIの仕様を含めたドキュメント生成・テスト・コード生成を行うフレームワーク全体を指した呼称です。
その中から、API仕様を定義するための標準部分のみ、Linux Foundationが後援する組織(OpenAPI Initialtive)によって管理されるようになり、その仕様のことをOpenAPIと呼ぶようです。
文法
OpenAPI文書は大きく分けて①metadata②servers③pathsの3つのセクションから構成されます。
openapi: 3.0.0
info:
title: Sample API
description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
version: 0.1.9
servers:
- url: http://api.example.com/v1
description: Optional server description, e.g. Main (production) server
- url: http://staging-api.example.com
description: Optional server description, e.g. Internal staging server for testing
paths:
/users:
get:
summary: Returns a list of users.
description: Optional extended description in CommonMark or HTML.
responses:
"200": # status code
description: A JSON array of user names
content:
application/json:
schema:
type: array
items:
type: string
Metadata
すべてのAPI定義にはOpenAPIの定義を記載する必要があります。
openapi: 3.0.0
infoセクションにはtitle, version, description(省略可）を含めます。
descriptionにはCommonMarkで定義されたMarkdownを含めることが出来ます。
info:
title: Sample API
description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
version: 0.1.9
Servers
ServersにはAPIサーバーと接続先URLを定義します。すべてのパスは接続先URLからの相対パスになります。(/usersはhttp://api.example.com/v1/usersやhttp://staging-api.example.com/usersになる)
servers:
- url: http://api.example.com/v1
description: Optional server description, e.g. Main (production) server
- url: http://staging-api.example.com
description: Optional server description, e.g. Internal staging server for testing
URL要素の変数化
URL内のあらゆる要素は変数化できます。変数化したい要素は{}で囲みます。その具体的な値はvariablesセクションに記載します。
任意値を入れたりenumで値域を制限したり出来ますが、default値が必ず必要です。
servers:
- url: https://{customerId}.saas-app.com:{port}/v2
variables:
customerId:
default: demo
description: Customer ID assigned by the service provider
port:
enum:
- '443'
- '8443'
default: '443'
Serversの上書き
servers内の項目はpaths内で上書きすることが出来ます。
servers:
- url: https://api.example.com/v1
paths:
/files:
description: File upload and download operations
servers:
- url: https://files.example.com
description: Override base path for all operations with the /files path
...
Paths
pathsセクションには個別のパスとHTTPメソッドを定義します。
paths:
/users:
get:
summary: Returns a list of users.
description: Optional extended description in CommonMark or HTML
responses:
"200":
description: A JSON array of user names
content:
application/json:
schema:
type: array
items:
type: string
すべてのパスは、Serversセクションで定義したbase URLからの相対パスとして宣言します。
pathsは短い説明のsummaryと長い説明descriptionをそれぞれ記載でき、descriptionはMetadataと同様、複数行記載でき、CommonMarkを使用できます。
パスパラメータ
URLの一部を{}で囲むことでパスパラメータを表現できます。
paths:
/users/{id}:
get:
HTTPメソッド
パスに対して複数のOperation(HTTPメソッド)を指定できます。OpenAPI 3.0ではget, post, put, patch, delete, head, options, traceに対応しています。
operationID
Operationそれぞれに対し、operationIDと呼ばれる、API内で一意のIDを定義できます。
/users:
get:
operationId: getUsers
summary: Gets all users
...
post:
operationId: addUser
summary: Adds a new user
...
/user/{id}:
get:
operationId: getUserById
summary: Gets a user by user ID
...
Deprecated
あるOperationが廃止されたことを示すdeprecatedオプションを付与できます。
/pet/findByTags:
get:
deprecated: true
SwaggerをUI表示するツールによっては廃止されたことを示す特別な表示がなされることがあります。
次回はパラメータ周りの書き方について。
Discussion