Swagger（OpenAPI3.0）に入門する（基本構成編）
この記事は，下記のサイトを参考にしています。
基本構成
OpenAPI の定義は、YAML あるいは JSON で記述することができます。
YAML で書かれた OpenAPI 3.0 の定義のサンプルは、次のようになります。
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
OpenAPIのバージョンは、API定義の全体的な構造、つまり、何をどのように文書化するかを定義します。
infoセクションには、title、description（任意項目）、versionなどの項目を含めます。
info:
title: Sample API
description: Optional multiline or single-line description in [CommonMark]
version: 0.1.9
- title : APIの名称
- description : APIに関する拡張情報。説明文は複数行にすることもできる。CommonMarkもサポートされている。
- version : APIのバージョンを指定する任意の文字列。（openapiバージョンと混同しないこと）major.minor.patchのようなセマンティックバージョニングでも、1.0-betaや2017-07-25のような任意の文字列も記載できる。
このほかに、termsOfService、contact、licenseなどの情報を記載できます。
Servers
serversセクションには、APIサーバとベースURLを指定できます。本番用やサンドボックス用など、1つまたは複数のサーバを定義することができます。
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
すべてのAPIパスは、相対パスです。
上記の例では、/usersは、使用するサーバーに応じて、http://api.example.com/v1/users または http://staging-api.example.com/users となります。
Paths
pathsセクションは、APIにおける個々のエンドポイントと、サポートするHTTPメソッドを定義します。例えば、GET /usersは、以下のように記述することができます。
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
Parameters
操作には、URL path（/users/{userId}）、query string（/users?role=admin）、headers （X-CustomHeader: Value）、cookies（Cookie: debug=0）経由でパラメータを渡すことが可能です。パラメータのデータ型、フォーマット、必須か任意か、その他の詳細を定義することができます。
paths:
/users/{userId}:
get:
summary: Returns a user by ID.
parameters:
- name: userId
in: path
required: true
description: Parameter description in CommonMark or HTML.
schema:
type : integer
format: int64
minimum: 1
responses:
'200':
description: OK
Request Body
操作でrequest bodyを送信する場合は、requestBody キーワードを使用してcontent およびmedia typeを記述します。
paths:
/users:
post:
summary: Creates a user.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
username:
type: string
responses:
'201':
description: Created
Responses
各操作に対して、200 OK や 404 Not Found などのステータスコードと、 レスポンスボディのスキーマを定義することができます。スキーマはインラインで定義することも、$ref で参照することもできます。また、さまざまなコンテンツタイプに対するレスポンスの例を提供することもできます。
paths:
/users/{userId}:
get:
summary: Returns a user by ID.
parameters:
- name: userId
in: path
required: true
description: The ID of the user to return.
schema:
type: integer
format: int64
minimum: 1
responses:
'200':
description: A user object.
content:
application/json:
schema:
type: object
properties:
id:
type: integer
format: int64
example: 4
name:
type: string
example: Jessica Smith
'400':
description: The specified user ID is invalid (not a number).
'404':
description: A user with the specified ID was not found.
default:
description: Unexpected error
レスポンスの HTTP ステータスコードは、引用符で囲む必要があることに注意してください。
"200" (OpenAPI 2.0 では不要でした)
Input and Output Models
グローバルコンポーネント/スキーマセクションでは、APIで使用する共通のデータ構造を定義することができます。これらは、パラメータやリクエストボディ、レスポンスボディなど、 スキーマが必要なときにいつでも $ref を使って参照することができます。たとえば、この JSON のようなものです。
{
"id": 4,
"name": "Arthur Dent"
}
上記を下記のように表現することができます。
components:
schemas:
User:
type: object
properties:
id:
type: integer
example: 4
name:
type: string
example: Arthur Dent
# Both properties are required
required:
- id
- name
そうすると、以下のようにリクエストボディスキーマとレスポンスボディスキーマで参照できるようになります。
paths:
/users/{userId}:
get:
summary: Returns a user by ID.
parameters:
- in: path
name: userId
required: true
schema:
type: integer
format: int64
minimum: 1
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/User' # <-------ここ
/users:
post:
summary: Creates a new user.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/User' # <-------ここ
responses:
'201':
description: Created
Authentication
securitySchemesおよびsecurityキーワードは、APIで使用する認証方法を記述するために使用されます。
components:
securitySchemes:
BasicAuth:
type: http
scheme: basic
security:
- BasicAuth: []
Full Specification
OpenAPI 3.0仕様の全文は、GitHubで公開されています。
Discussion