Swagger備忘録

Swaggerとは？

  • RESTful APIを設計する際のドキュメンテーションやテストを助けるフレームワー ク
  • 記述方式はyamlまたはjson
  • Swaggerを記述すると、JavaDocのような形式でAPIのドキュメントを作成、Webで閲覧できるようになる。
  • APIのパスやリクエスト、レスポンスパラメータを管理し、実際にパラメータの送受信テストまで行える。
  • WEB(画面)資源からコールするAPIの上右方なので、APIの出入り口、つまり、Controllerのリクエストレスポンスについて記述する。
  • Swagger Editorを使用して書くこともできる

Swaggerファイルの保存ディレクトリの例

src/docs/openapi/yaml/xxx.yaml

プレビュー

設定> 拡張機能> Swagger Viewer を導入するとプレビュー(Alt + Shift +
P)が使用できる

Swaggerの記述方法（コーディング）

使用できる主な型は以下

  • array
  • string
  • integer
  • boolean
  • array
  • object

サンプルコード

#はじめにAPIの定義情報を一覧で記述するエリア
tags:
  - name: SAPMPLE
    description: Smaple Description
  - name: SAMPLE2
    description: Smaple Description2

#各APIの詳細情報を記述する
paths:  #URLに応じたメソッド単位の処理を書く
  /xxx/xxx: #URL。クエリパラメータも表示したい場合は${}で記述
    post: #get or post
      tags:
        - SAPMPLE #どのAPIの情報なのか、冒頭で記述したtagsから選択
      summary: サンプルAPI  #タイトルみたいなもの
      description: #メソッドについての概要
      parameters: #クエリ(URL)もしくはリクエストヘッダで渡されるパラメータ
        - $ref: '#/components/parameters/UserId'  ##参照($ref)するパラメータ。コンポーネントエリアで記述してあるものを参照できる
        - name: sampleId
          in: path
          description: サンプルID
          required: true
          type: integer
          format: int64
      requestBody:
        description: リクエストの概要
        content:
          application/json: #リクエストの形式。 jsonかyaml か
            schema:
              $ref: #components/schemas/User #postするオブジェクト
              #オブジェクトではなく値をpostする場合............................................................
              properties:
                userId:
                  description: sample
                  type: string
                  example: sample
              #............................................................
      responses:
        '200': #ステータスコード
          description:  #レスポンスの概要
            content:
              application/json:
                schema:
                  type: array
                  items:  #typeがarrayの場合に、格納されるオブジェクトの情報をitems配下に記述する
                    $ref: '#/components/schemas/User' #参照($ref)すするモデル。コンポーネントエリアで記述してあるものを参照できる
                  exapmple:
                    - id: 1
                      name: John
                    - id: 2
                      name: Bob

#…同じ要領で各APIの情報を記述する…

#コンポーネントエリア
#汎用的に使用したいオブジェクトはcomponentとして定義しておくことで、他から参照できる
components:
  parameters: #クエリパラメータ、ヘッダーパラメータを定義するエリア
    UserId:
      name: userId
      in: header  #header or path クエリパラメータかヘッダーパラメータか
      schema:
        type: string
        
  schemas:  #ボディ用のオブジェクトを定義するエリア
    User: #モデル名
      type object #下のプロパティをオブジェクトにするのか配列にするのか
      required: #必須フィールド
        - id
      properties: #オブジェクトのプロパティ
        id:
          type: integer
          example: '123456' #サンプルの値を記述
        name:
          type: string
        exapmple: #サンプルの値をオブジェクト単位でまとめて書く場合
          - id: 1
            name: John

Date型の表現方法

Date型など、ここにない型を表現したい場合は、typeとformatの組み合わせで表現する。

parameters:
  name: date
  in: path
  description: 日付
  type: string
  format: date

参考：OpenAPI

継承（extends）の表現

allOfを使用する。

SampleAdditional:
  description: サンプル
  all0f:
    - $ref: '#/components/schemas/Sample' #Sampleオブジェクトを継承
    - type: object
      properties:
        name: additionalProp  #追加プロパティ
        type: string

参考：Swagger_allOf

Bodyを必要としない場合

クエリパラメータのみで、RequestBodyを必要としない、もしくは、レスポンスがvoidの場合は、以下だけ指定すればOK。

schema:
  type: object

Appendix

パラメータに付与するハイフン『-』の意味

yamlの書き方。『-』を付けたものは配列として扱われる。

コメント

タイトルとURLをコピーしました