Swaggerの読み方

この記事の目的

Swaggerが読めるようになること。

目次

1. Swaggerとは
2. Swagger Editor
3. Swaggerの単語説明

Swaggerとは

OpenAIの仕様で記述されたAPIドキュメント。
jsonとyamlで記述できる。
以下公式ドキュメント。
Swagger

Swagger Editor

Swaggerをより視覚的に見やすくするためのツール。
freeで使えるのは以下3つ。

1. Swagger Editor
2. Swagger Codegen
3. 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