Swaggerについて

ふじしろ

必須の項目は以下３つ。これが記載されていれば動く。

openapi
info
paths

ふじしろ

coponents/difinitionsについて

繰り返し使用する記述を共通化させることができる仕組み。
openapi（swagger 3.0）になってからはconponentsと呼ばれているが、
swagger（swagger 2.0）の頃はdefinitionsと呼ばれていた模様

ふじしろ

serversについて

servers:
  - url: https://example.com/api

のように記述し、pathsの手前の共通するURLを定義できる。

この記事では、APIのベースパスを指定すると表現されていた

ふじしろ

serversに共通するURL記述
URL設計をもとにpathsにパスを一通り書いていく
URL設計をもとにpathsのメソッドを一通り書いていく
infoを以下に絞る
1. title
2. description
3. contact
4. version
serversに変数を活用したurlを記載
pathsの各メソッドに以下の項目を記述：参考
- summary
- description
- operationId（書き方がわからなかったのでノリで記述）
- response（中身は空）
- ここまで書くと大枠が出来上がる。
pathsの各メソッドに必要に応じて以下の項目を追記：実用的なOASを書く
- parameters
  - クエリ文字列またはパスパラメータがなければ不要
- requestBody（schemaは後回し）
  - 今回の場合、getとdeleteでは不要
- response（成功時のレスポンスのみ記述してエラーは後回し。schemaも後回し）
  - descriptionは必須とのこと
componentsとschemaを作成：componentsとschema
tagを作成してグルーピング

ふじしろ

タグ名	内容
info	概要を記述する
servers	サーバーのURIやAPIのベースパスを指定する
tags	APIをグルーピングして表示するためのタグを生成する
paths	API仕様書の中心。ここにAPIのURLやメソッドを記述する
components	schemaなどAPI仕様書内で繰り返し使用する要素を生成する

ふじしろ

同じステータスコードで異なるエラーレスポンスを返す時の記述方法がわからない

参考記事

記述例

以下のように記述することで、Examplesによりレスポンスを切り替えることができる。

# パスの記述
paths:
  /pets:
    get:
      responses:
        '200':
           $ref: '#/components/responses/Responses' 
# コンポーネントの構成
components:
  responses:
    Responses:
      description: 同じステータスコードから複数のレスポンスを返すことができます。
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/responses/Response1'
              - $ref: '#/components/responses/Response2'
              - $ref: '#/components/responses/Response3'
          examples:
            Reaponse1:
              value:
                status: 400
                message: レスポンス１
            Reaponse2:
              value:
                status: 400
                message: レスポンス２
            Reaponse3:
              value:
                status: 400
                message: レスポンス３
# oneOfで記述しているResponseの記述は省略

ふじしろ

ファイルアップロード時の書き方

openapi: 3.0.0
info:
  title: HogeHoge
  version: 1.0.0
paths:
  /hoge:
    post:
      requestBody:
        content:
          image/*:
            schema:
              type: string
              format: binary
      responses:
        "200":
          description: ok

OpenAPI Specification 3.0 チートシート - 朝日ネット　技術者ブログ

ふじしろ

Bearer認証の記述

Bearer Authentication

openapi: 3.0.0
...
# 1) Define the security scheme type (HTTP bearer)
components:
  securitySchemes:
    bearerAuth:            # arbitrary name for the security scheme
      type: http
      scheme: bearer
      bearerFormat: JWT    # optional, arbitrary value for documentation purposes
# 2) Apply the security globally to all operations
security:
  - bearerAuth: []         # use the same name as above