ポケモンで学ぶSwagger(OpenAPI)

openapi3系で書きます

バージョン違うとエラーが出ます。

最新で頑張るのだ！(｡- .•)

Swagger EditorでDeleteを定義したけれど、delete_flg, invalid_flgといった論理削除や論理無効化で処理することが多いっぽい。だから実践ではDeleteメソッドは利用せず、PUTメソッドを利用したUPDATE処理で論理削除を行うことが多いのだろうな。

@see

OpenAPI Specification 3.0 チートシート(外部サイト)
ReDoc(外部サイト)
SwaggerのyamlをHTMLドキュメントに変換してくれるサービス

CRUDが一通りできた

openapi: 3.0.0
info:
  title: ポケモンで学ぶSwagger(OpenAPI) + Laravel API
  version: 1.0.1
servers:
  - url: http://localhost/api/v1_01
tags:
  - name: master
    description: ユーザ情報API
paths:
  /master/getProfiles:
    get:
      summary: ユーザ情報一覧取得
      description: |
      tags:
        - master
      parameters: 
        - in: query
          name: master_id
          required: false
          schema:
            type: integer
            format: int64
            example: 999
      responses:
        '200':
          description: 成功時のレスポンス
          content:
            application/json:
              schema:
                type: object
                properties:
                  profile:
                    $ref: '#/components/schemas/MasterProfile'
                  action:
                    $ref: '#/components/schemas/MasterAction'
  
  /master/getProfile/{master_id}:
    get:
      summary: ユーザ情報を指定して取得
      description: |
      tags:
        - master
      parameters:
        - in: path
          name: master_id
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 成功時のレスポンス
          content:
            application/json:
              schema:
                type: object
                properties:
                  profile:
                    $ref: '#/components/schemas/MasterProfile'
                  action:
                    $ref: '#/components/schemas/MasterAction'
        '400':
          description: 禁止・無効なユーザーID
        '404':
          description: ユーザーが見つけられません。
  
  /master/storeProfile:
    post:
      summary: ユーザ情報を登録
      description: |
      tags:
        - master
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  format: string
                age:
                  type: integer
                  format: int64
              example:
                name: "yuu"
                age: 12
      responses:
        '200':
          description: 成功時のレスポンス
        '400':
          description: 禁止・無効なユーザーID
        '404':
          description: ユーザーが見つけられません。
  /master/updateProfile:
    put:
      summary: ユーザ情報を更新
      description: |
      tags:
        - master
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                profile:
                  $ref: '#/components/schemas/UpdateMasterReq'
      responses:
        '200':
          description: 成功時のレスポンス
        '400':
          description: 禁止・無効なユーザーID
        '404':
          description: ユーザーが見つけられません。
  /master/destroy/{master_id}:
    delete:
      summary: ユーザ情報を指定して削除
      description: |
      tags:
        - master
      parameters:
        - in: path
          name: master_id
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: 成功時のレスポンス
        '400':
          description: 禁止・無効なユーザーID
        '404':
          description: ユーザーが見つけられません。
        '550':
          description: その他のエラー




components:
  schemas:
    Master:
      type: object
      properties:
        id: 
          type: integer
          format: int64
        name: 
          type: string
        age: 
          type: integer
    UpdateMasterReq:
      type: object
      required:
        - master_id
      properties:
        master_id:
          type: integer
        name:
          type: string
        age:
          type: integer
      example:
        master_id: 999
        name: "yuu"
        age: 12
    MasterProfile:
      type: object
      properties:
        name:
          type: string
          format: string
          description: ユーザ名
          example: "yuu"
        age:
          type: integer
          format: int64
          description: ユーザの年齢
          example: 12
    MasterAction:
      type: object
      properties:
        dougu:
          type: object
          properties:
            name:
              type: string
              description: アイテム名
              format: string
              example: "きずぐすり"
        pokemon:
          type: object
          properties:
            name:
              type: string
              format: string
              description: ポケモン名

components

２回以上利用するオブジェクトはcomponentsで定義して、使いまわせるようにします。
404などのサーバレスポンスもcomponentsで定義するとすっきりします。

定義

components:
  schemas:
    Master:
      type: object
      properties:
        id: 
          type: integer
          format: int64
        name: 
          type: string
        age: 
          type: integer

componentsでMasterを定義

参照方法

      responses:
        '200':
          description: 成功時のレスポンス
          content:
            application/json:
              schema:
                type: object
                properties:
                  profile:
                    $ref: '#/components/schemas/MasterProfile'

$ref: ‘#/components/schemas/MasterProfile’で階層型で指定します。

JWTのログインAPI機能を定義する

ここを見るですね。
https://swagger.io/docs/specification/authentication/bearer-authentication/

ログイン周りも追加

完成系

順番も整理しました。

サマリー情報定義
・openapi: 3.0.0
・info:
・servers:
・tags:
components定義
・ログイン系
・securitySchemes:
・requestBodies:
・RefreshToken:
・レスポンス
・responses:
・スキーマ
・schemas:
パス定義
・paths

openapi: 3.0.0
info:
  title: ポケモンで学ぶSwagger(OpenAPI) + Laravel API
  version: 1.0.1
servers:
  - url: http://localhost/api/v1_01
tags:
  - name: login
    description: ログイン
  - name: master
    description: ユーザ情報操作

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Credentials or access token for API
      bearerFormat: JWT
  requestBodies:
    Account:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              id:
                type: string
                description: アカウントIDを表す文字列
                example: 'yuuSan55'
              password:
                type: string
                description: アカウントのパスワードを表す文字列
                example: 'P@ssw0rd'
            required:
              - id
              - password
    RefreshToken:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              refresh_token:
                type: string
                description: リフレッシュトークンを指定します。
                example: example_refresh_token
            required:
              - refresh_token
  responses:
    400BadRequestError:
      description: リクエスト不正の際のエラーレスポンス
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                description: エラーを表すオブジェクト
                properties:
                  error_code:
                    type: number
                    description: |
                      エラーコードをあらわす数値

                      * 400001 - リクエストの形式が間違っています。必須の入力項目が足りない。
                    example: 400001
                  message:
                    type: string
                    description: エラーメッセージを表す文字列
                    example: リクエスト形式が間違っています。
    401LoginError:
      description: |
        認証エラーを表すエラーコード
        * IDもしくはパスワードが間違っている
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                description: エラーを表すオブジェクト
                properties:
                  error_code:
                    type: number
                    description: |
                      エラーコードを表す数値

                      * 401001 - ログインIDもしくはパスワードが間違っている
                      * 401002 - アカウントがロックされている。(n回連続ログイン失敗でブロック。１時間後に解除します。)
                    example: 401001
                  message:
                    type: string
                    description: エラーメッセージをあらわす文字列
                    example: 認証に失敗しました。IDとパスワードを確認してください。
    401TokenRefreshError:
      description: 認証系エラーレスポンス
      content:
        application/json:
          schema:
            type: object
            description: エラーを表すオブジェクト
            properties:
              error:
                type: object
                properties:
                  error_code:
                    type: number
                    description: |
                      エラーコードを表す数値

                      * 401001 - リフレッシュトークンが無効
                      * 401002 - リフレッシュトークンの有効期限切れ
                    example: 401001
                  message:
                    type: string
                    description: エラーメッセージを表す文字列
                    example: 無効なリフレッシュトークン
    403LoginError:
      description: アクセス禁止エラーレスポンス
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                description: エラーを表すオブジェクト
                properties:
                  error_code:
                    type: number
                    description: |
                      エラーコードを表す数値

                      * 403001 - アカウントが停止されている
                      * 403002 - アカウントが退会している
                    example: 403001
                  message:
                    type: string
                    description: エラーメッセージを表す文字列
                    example: このユーザは退会しています。
    403AcountBanError:
      description: アクセス禁止エラーレスポンス
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                description: エラーを表すオブジェクト
                properties:
                  error_code:
                    type: number
                    description: |
                      エラーコードを表す数値

                      * 403001 - アカウントが停止されています
                    example: 403001
                  message:
                    type: string
                    description: エラーメッセージを表す文字列
                    example: アカウントが停止されています。
  schemas:
    Token:
      type: object
      description: トークンを表すオブジェクト
      properties:
        access_token:
          type: string
          description: |
              * トークンのオブジェクトを定義
              * アクセストークン, リフレッシュトークンを定義
              * 30分でアクセストークンは期限切れとなり、リフレッシュトークンによって新規のアクセストークンを取得します。
          example: hoge_access_token
        refresh_token:
          type: string
          description: |
          example: hoge_refresh_token
    Master:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        age:
          type: integer
        del_flg:
          type: integer
          description: |
            アカウントが削除されているかを表す整数
            0: アカウントがアクティブ
            1: アカウント削除済
        invalid_flg:
          type: integer
          description: |
            アカウントが有効、無効を表す整数
            0: アカウント有効
            1: アカウント無効化済
          example: 0
    MasterProfile:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: ユーザidを表す整数
          example: 999
        name:
          type: string
          format: string
          description: ユーザ名を表す文字列
          example: "yuu"
        age:
          type: integer
          format: int64
          description: ユーザの年齢を表す数字
          example: 12
    MasterAction:
      type: object
      properties:
        dougu:
          type: object
          properties:
            name:
              type: string
              description: アイテム名を表す文字列
              example: "きずぐすり"
        pokemon:
          type: object
          properties:
            name:
              type: string
              example: "ピカチュウ"
              description: ポケモン名を表す文字列
    UpdateMasterReq:
      type: object
      required:
        - master_id
      properties:
        master_id:
          type: integer
        name:
          type: string
        age:
          type: integer
      example:
        master_id: 999
        name: "yuu"
        age: 12


security:
  - bearerAuth: []
paths:
  /login:
    post:
      security: []
      summary: アカウントログイン実行
      description: |
        アカウントでログインを実行する
      tags:
        - login
      requestBody:
        $ref: '#/components/requestBodies/Account'
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    $ref: '#/components/schemas/Token'
                  profile:
                    $ref: '#/components/schemas/MasterProfile'
        '400':
          $ref: '#/components/responses/400BadRequestError'
        '401':
          $ref: '#/components/responses/401LoginError'
        '403':
          $ref: '#/components/responses/403LoginError'
  /refresh-token:
    post:
      security: []
      summary: トークンをリフレッシュします。
      description: |
        リフレッシュトークンを得て、新しいアクセストークンとリフレッシュトークンを払い出します。
      tags:
        - login
      requestBody:
        $ref: '#/components/requestBodies/RefreshToken'
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
        '400':
          $ref: '#/components/responses/400BadRequestError'
        '401':
          $ref: '#/components/responses/401TokenRefreshError'
        '403':
          $ref: '#/components/responses/403AcountBanError'
  /master/getProfiles:
    get:
      summary: ユーザ情報一覧取得
      description: |
      tags:
        - master
      parameters:
        - in: query
          name: master_id
          required: false
          schema:
            type: integer
            format: int64
            example: 999
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  profile:
                    $ref: '#/components/schemas/MasterProfile'
                  action:
                    $ref: '#/components/schemas/MasterAction'
        '400':
          $ref: '#/components/responses/400BadRequestError'
  /master/getProfile/{master_id}:
    get:
      summary: ユーザ情報を指定して取得
      description: ユーザ情報をmaster_idで指定して取得します。
      tags:
        - master
      parameters:
        - in: path
          name: master_id
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Success Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  profile:
                    $ref: '#/components/schemas/MasterProfile'
                  action:
                    $ref: '#/components/schemas/MasterAction'
        '400':
          $ref: '#/components/responses/400BadRequestError'
  /master/storeProfile:
    post:
      summary: ユーザ情報を登録
      description: |
      tags:
        - master
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  format: string
                age:
                  type: integer
                  format: int64
              example:
                name: "yuu"
                age: 12
      responses:
        '200':
          description: Success Response
        '400':
          $ref: '#/components/responses/400BadRequestError'
  /master/updateProfile:
    put:
      summary: ユーザ情報を更新
      description: |
      tags:
        - master
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                profile:
                  $ref: '#/components/schemas/UpdateMasterReq'
      responses:
        '200':
          description: Success Response
        '400':
          $ref: '#/components/responses/400BadRequestError'
  /master/destroy/{master_id}:
    post:
      summary: ユーザ情報を指定して削除
      description: |
      tags:
        - master
      parameters:
        - in: path
          name: master_id
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Success Response
        '400':
          $ref: '#/components/responses/400BadRequestError'

優技録

ポケモンで学ぶSwagger(OpenAPI)

openapi3系で書きます

CRUDが一通りできた

components

定義

参照方法

JWTのログインAPI機能を定義する

ログイン周りも追加

完成系

関連記事 - More from my site -

コメントを残すコメントをキャンセル

openapi3系で書きます

CRUDが一通りできた

components

定義

参照方法

JWTのログインAPI機能を定義する

ログイン周りも追加

完成系

関連記事 - More from my site -

コメントを残す コメントをキャンセル

コメントを残すコメントをキャンセル