この記事の目的
Swaggerが読めるようになること。
目次
- Swaggerとは
- Swagger Editor
- Swaggerの単語説明
Swaggerとは
OpenAIの仕様で記述されたAPIドキュメント。
jsonとyamlで記述できる。
以下公式ドキュメント。
Swagger
Swagger Editor
Swaggerをより視覚的に見やすくするためのツール。
freeで使えるのは以下3つ。
- Swagger Editor
- Swagger Codegen
- Swagger UI
今回はSwagger Editorを使用。
Swaggerが提供しているものもあるが、以下でローカルに落として実行も可能。
git clone https://github.com/swagger-api/swagger-editor.git
npm run start
http://localhost:3200 にアクセス。
ブラウザ上で確認が可能。
Swaggerの単語説明
OpenAPI Object
ルートとなるカテゴリ。openapiとinfoは必須。
openapi:
info:
externalDocs:
servers:
tags:
paths:
components:
Paths Object
/{path}
APIエンドポイントへの相対パス。絶対パスはservers/url/{path}になる。
Paths Item Object・Operation Object
単一のパスにアクセスしたときの操作を記載されている。
以下のsampleは、
・/pet/{petId}にgetでアクセスした場合。
・IDでpetを検索し、そのpetの情報を返す。
・パラメータは、petIdと定義し、クエリーパラメータ。
クエリーパラメータは必須で、integer型で符号付で64bitまで
・レスポンス
200 → 成功。application/jsonで返す。response bodyは/components/schemas/Petに記載のもの。
400 → 失敗。IDが不正。
404 → 失敗。IDに紐づくPet情報がない。
paths:
/pet/{petId}:
get:
tags:
- pet
summary: Find pet by ID
description: Returns a single pet
operationId: getPetById
parameters:
- name: petId
in: path
description: ID of pet to return
required: true
schema:
type: integer
format: int64
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
application/xml:
schema:
$ref: '#/components/schemas/Pet'
'400':
description: Invalid ID supplied
'404':
description: Pet not found
Schema Object
入出力の項目やデータ型を定義している。
以下のsampleは、
・Petスキーマには、id,name,category,photoUrls,tags,statusの項目を持っている。
components:
schemas:
Pet:
required:
- name
- photoUrls
type: object
properties:
id:
type: integer
format: int64
example: 10
name:
type: string
example: doggie
category:
$ref: '#/components/schemas/Category'
photoUrls:
type: array
xml:
wrapped: true
items:
type: string
xml:
name: photoUrl
tags:
type: array
xml:
wrapped: true
items:
$ref: '#/components/schemas/Tag'
status:
type: string
description: pet status in the store
enum:
- available
- pending
- sold
xml:
name: pet