Swagger 高度な機能

components を使用して定義を再利用する

Schema（データモデル）の再利用

components を使用すると、API ドキュメント全体で再利用できる要素を定義でき、重複を減らして一貫性を確保できます：

例

components:
schemas:
User:
type: object
properties:
id:
type: integer
format: int64
username:
type: string
email:
type: string

参照方法：

例

paths:
/users/{id}:
get:
responses:
'200':
description:ユーザー情報
content:
application/json:
schema:
$ref: '#/components/schemas/User'

Parameters（共通パラメータ）の再利用

よく使うパラメータを定義：

例

components:
parameters:
PageParam:
name: page
in: query
schema:
type: integer
default: 1
description:ページ番号
LimitParam:
name: limit
in: query
schema:
type: integer
default: 10
description:1ページあたりのレコード数

参照方法：

例

paths:
/products:
get:
parameters:
- $ref: '#/components/parameters/PageParam'
- $ref: '#/components/parameters/LimitParam'

Responses（共通レスポンス）の再利用

標準レスポンスを定義：

例

components:
responses:
NotFound:
description:リソースが見つかりません
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 404
message:
type: string
example: "リソースは存在しません"
BadRequest:
description:リクエストパラメータエラー
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 400
message:
type: string

参照方法：

例

paths:
/users/{id}:
get:
responses:
'200':
description:成功
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'404':
$ref: '#/components/responses/NotFound'
'400':
$ref: '#/components/responses/BadRequest'

API バージョン管理

servers によるバージョン区別

例

servers:
- url: https://api.example.com/v1
description: API v1
- url: https://api.example.com/v2
description: API v2

パスによるバージョン区別

例

paths:
/v1/users:
get:
# v1 ユーザーAPI...

/v2/users:
get:
# v2 ユーザーAPI...

リクエストヘッダーによるバージョン区別

例

paths:
/users:
get:
parameters:
- name: api-version
in: header
required: true
schema:
type: string
enum: ['1.0', '2.0']

Mock データシミュレーション

examples を使用してサンプルデータを定義する

レスポンス内でサンプルを定義：

例

paths:
/users:
get:
responses:
'200':
description:ユーザーリスト
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
examples:
userList:
summary:サンプルユーザーリスト
value:
- id: 1
username: "user1"
email: "[email protected]"
- id: 2
username: "user2"
email: "[email protected]"

Swagger UI Mock 機能を使用する

Swagger UI にはモックサーバーが統合されており、OpenAPI 定義に基づいてモックレスポンスを生成できます。

mockServer を Swagger UI に設定：

例

SwaggerUI({
url: "https://petstore.swagger.io/v2/swagger.json",
dom_id: '#swagger-ui',
presets: [
SwaggerUI.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUI.plugins.MockPlugin
],
mockImplementations: {
'/users': {
get: () => ({
status: 200,
body: [
{ id: 1, name: "Test User 1" },
{ id: 2, name: "Test User 2" }
]
})
}
}
})

サードパーティの Mock サービスを使用する

Prism: OpenAPI モックサーバー
Mockoon: Swagger と統合できるモック API ツール
Postman: mock サーバー機能を提供

高度なセキュリティ設定

複数の認証方法を定義：

例

components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
apiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
OAuth2:
type: oauth2
flows:
implicit:
authorizationUrl: https://example.com/oauth/authorize
scopes:
read:読み取り権限
write:書き込み権限

セキュリティ定義を適用：

例

security:
- bearerAuth: []
- apiKeyAuth: []

paths:
/users:
get:
security:
- OAuth2: [read]

ドキュメントの分離と整理

使用$ref外部ファイルを参照：

例

paths:
/users:
$ref: './paths/users.yaml'
/products:
$ref: './paths/products.yaml'

components:
schemas:
User:
$ref: './schemas/user.yaml'

タグとグループ化

タグを使用して API エンドポイントを整理：

例

tags:
- name: users
description:ユーザー管理
- name: products
description:製品管理

paths:
/users:
get:
tags:
- users
/products:
get:
tags:
- products

拡張フィールド

によってx-プレフィックスでカスタム属性を追加：

例

lpaths:
/users:
get:
x-controller: UserController
x-rate-limit: 100
x-deprecated: false

これらの高度な機能は、より構造化され、保守性が高く、プロフェッショナルな API ドキュメントを作成するのに役立ちます。

その他の拡張