はじめに
Swagger(Swagger Editor)を触る機会ができたので、OAS3.0について軽く調べたことをメモする。
最初、Swagger 2.0とOpenAPI 3.0の違いがわからず混乱した。
Live Demo では、Swagger2.0のサンプルコードが記載されている。
本記事の内容について、参考サイトは下記の通り。
About Swagger Specification | Documentation | Swagger
OpenAPI Specification
OpenAPIってなに？
**OpenAPI Specification(OAS)**は、REST APIのためのAPI記述形式。
- エンドポイント(/users)と各操作(GET,POSTなど)
- パラメーターと入出力
- 認証方法
YAMLかJSONで記述できる。
Swaggerってなに？
OAS仕様に基づいたオープンソースツールで、REST APIの設計、構築、文書化、及び使用に役立つ。
基本構造
雰囲気はこんな感じ。
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
メタデータ
openapi: 3.0.0
Paths
APIの個々のエンドポイント（パス）と、対応するHTTPメソッドを定義できる。
下記の情報を含めることができる。
- パラメーター
- リクエストボディ
- レスポンスのステータスコード（200,400）
- レスポンスの中身（コンテンツ）
Parameters
URLパス（/users/{userId}）、クエリ文字列（/users?role=admin）、ヘッダー（X-CustomHeader: Value）、またはCookie（Cookie: debug=0）を介してパラメーターを渡すことができる。
データ型、形式、必須などを定義できる。
Request Body
requestBodyキーワードを使用して本文のコンテンツとメディアタイプを記述できる。
Responses
ステータスコードとレスポンスボディ(schema)を定義できる。
スキーマは、インラインで定義することも、[$ref](https://swagger.io/docs/specification/using-ref/)を介して参照することもできる。
HTTPステータスコードは、引用符で囲む必要あることに注意する。
responses:
'200':
description: A user object.
Input and Output Models
グローバル セクションcomponents/schemasでは、APIで使用される一般的なデータ構造を定義できる。
パラメータ、リクエストボディ、レスポンスボディなど必要なときに $ref で参照できる。
components:
schemas:
User:
type: object
properties:
id:
type: integer
example: 4
name:
type: string
example: Arthur Dent
# Both properties are required
required:
- id
- name
レスポンスやリクエストボディで参照するとき。
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/User'
〜〜〜
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/User'
Authentication
securitySchemesとsecurityキーワードは、APIで使用される認証方法を説明するために使用される。
components:
securitySchemes:
BasicAuth:
type: http
scheme: basic
security:
- BasicAuth: []
サポートされる認証法は以下の通り。
- HTTP認証
- APIキー（ヘッダー、クエリパラメータ、Cookie）
- OAuth 2
- OpenID Connect Discovery
Media Types
リクエストやレスポンスボディのデータ形式のこと。
JSON、XML、画像が一般的。
paths:
/employees:
get:
summary: Returns a list of employees.
responses:
'200': # Response
description: OK
content: # Response body
application/json: # Media type
schema: # Must-have
type: object # Data type
properties:
id:
type: integer
name:
type: string
fullTime:
type: boolean
example: # Sample data
id: 1
name: Jessica Right
fullTime: true
メディアタイプ名の一覧
application/json
application/xml
application/x-www-form-urlencoded
multipart/form-data
text/plain; charset=utf-8
text/html
application/pdf
image/png
componentsから参照
content: # Response body
application/json: # Media type
schema:
$ref: '#/components/schemas/Employee' # Reference to object definition
application/xml: # Media type
schema:
$ref: '#/components/schemas/Employee' # Reference to object definition
components:
schemas:
Employee: # Object definition
type: object
properties:
id:
type: integer
name:
type: string
fullTime:
type: boolean
Paths and Operations
OASのグローバルセクションで定義される。
paths:
/ping:
...
/users:
...
/users/{id}:
...
パステンプレート
中括弧{}を使用して、URLの一部をパスパラメータとしてマークできる。
Operations
OAS3.0では、get, post, put, patch, delete, head, options,trace をサポートする。
1つのパスで複数の操作をサポートできる。
tags–リソースまたはその他の修飾子によって操作を論理的にグループ化するために使用される。
paths:
/users/{id}:
get:
tags:
- Users
summary: Gets a user by ID.
パス内のクエリ文字列
パスにクエリ文字列パラメータを含めることができない。代わりに、クエリパラメータとして定義する必要がある。
paths:
/users:
get:
parameters:
- in: query
name: role
schema:
type: string
enum: [user, poweruser, admin]
required: true
operrationId
操作を識別するために使用されるオプションの一意の文字列。
/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
...
データモデル（スキーマ）
今後、抑えたい。
Components Section
例。
components:
#-------------------------------
# Reusable schemas (data models)
#-------------------------------
schemas:
User: # Can be referenced as '#/components/schemas/User'
type: object
properties:
id:
type: integer
format: int64
name:
type: string
Error: # Can be referenced as '#/components/schemas/Error'
type: object
properties:
code:
type: integer
message:
type: string
#-------------------------------
# Reusable operation parameters
#-------------------------------
parameters:
offsetParam: # Can be referenced via '#/components/parameters/offsetParam'
name: offset
in: query
description: Number of items to skip before returning the results.
required: false
schema:
type: integer
format: int32
minimum: 0
default: 0
limitParam: # Can be referenced as '#/components/parameters/limitParam'
name: limit
in: query
description: Maximum number of items to return.
required: false
schema:
type: integer
format: int32
minimum: 1
maximum: 100
default: 20
#-------------------------------
# Reusable responses
#-------------------------------
responses:
404NotFound: # Can be referenced as '#/components/responses/404NotFound'
description: The specified resource was not found.
ImageResponse: # Can be referenced as '#/components/responses/ImageResponse'
description: An image.
content:
image/*:
schema:
type: string
format: binary
GenericError: # Can be referenced as '#/components/responses/GenericError'
description: An error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
おわりに
こっちのドキュメント 読む前に、力尽きた。
OASの雰囲気は把握できたので、参考にしながらであれば記述できそう。
認証まわりは全く理解していないので、また今度調べたい。