Web API

hbsnow

SSKDs - Small set of known developers
LSUDs - Large set of unknown developers

hbsnow

Swagger UI
Swagger Editor
Swagger Codegen

hbsnow

VIewer なら VSCode のプラグインの swagger-viewer だったり Stoplight を使ってる。swagger-viewerはエラーがでないのであくまで読む用。

VSCodeで更新が必要ならこっちもいれる

hbsnow

https://swagger.io/specification/

hbsnow

ルートのOpenAPIドキュメントにはopenapi.jsonまたはopenapi.yamlの名前がつけられることがおすすめされています。

hbsnow

OpenAPI Specification (OAS)

hbsnow

OpenAPI Object

OpenAPIドキュメントのルートドキュメントオブジェクト

openapi REQUIRED
- OpenAPIのバージョン、最新は 3.0.3
info REQUIRED
- APIに関するメタデータ
servers
- サーバーへの接続情報。デフォルト値はURL値が/のサーバーオブジェクト
paths REQUIRED
- APIの利用可能なパスとoperations
components
- 仕様書の様々なスキーマを保持するためのelement
security
- API全体でどのセキュリティメカニズムを使用できるか
tags
- 仕様書で使用されているタグのリストに、追加のメタデータを加えたもの
externalDocs
- 外部ドキュメント

hbsnow

openapi

openapi: 3.0.3

hbsnow

info

info:
  title: 生地の在庫管理システム
  version: 1.0.0

hbsnow

server

servers:
  - url: http://localhost:8010/v1
    description: Localhost server
  - url: http://dev.excample.com/v1
    description: Development server
  - url: http://stg.excample.com/v1
    description: Staging server
  - url: http://api.excample.com/v1
    description: Production server

hbsnow

path

Operation Object

operationId - OpenAPI Generator でメソッド名などに使用される。すべての Operation で一意でなければならない

Schema Object

integer - 整数
number - 小数
string
boolean
array
object

formatはオープンな値なので、OpenAPI仕様で定義されていないフォーマットであっても使用することができます。

paths:
  /cloths:
    get:
      tags:
        - cloth
      summary: 生地一覧
      description: 所持している生地の一覧
      operationid: getCloths
      responses:
        "200":
          description: 生地の一覧
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  description: 生地データ
                  required:
                    - clothId
                    - photo
                    - price
                    - createdAt
                    - updatedAt
                  properties:
                    clothId:
                      type: string
                      description: 生地ID
                      example: cloth0001
                    photo:
                      type: string
                      format: uri
                      description: 生地の写真の URL
                      example: https://example.com/cloth0001.jpg
                    price:
                      type: integer
                      description: 10cm単位の価格
                      example: 300
                    createdAt:
                      type: string
                      format: date-time
                      description: 作成日
                    updatedAt:
                      type: string
                      format: date-time
                      description: 更新日

hbsnow