Swagger Snippets

[RammusXu]

---

title: 在 Playframework 開發 swagger.io 的範例 date: 2016-11-18 03:45:04 tags: ["Playframework", "swagger"]

parameters 用法

swagger.yml

  parameters:
    authParam:
      name: Authorization
      description: sessionId
      in: header
      required: ture
      type: string

routes

###
#  tags: ["Auth"]
#  summary: 登出
#  parameters:
#    - $ref: '#/parameters/authParam'
#  responses:
#    '200':
#       description: 登出成功.
#    '401':
#       description: Auth驗證失敗.
###
DELETE  /logout                     controllers.AuthController.logout

More info: http://swagger.io/specification/#parameterObject

responses 用法

swagger.yml

  responses:
    AuthError:
      description: Auth 驗證失敗

routes

###
#  tags: ["Auth"]
#  summary: 登出
#  parameters:
#    - $ref: '#/parameters/authParam'
#  responses:
#    '200':
#       description: 登出成功.
#    '401':
#       $ref: '#/responses/AuthError'
###
DELETE  /logout                     controllers.AuthController.logout

More info: http://swagger.io/specification/#responseObject

definitions 用法 - 1

swagger.yml - 新增一個 Admin 的物件

  definitions:
    Admin:
      type: object
      required:
      - account
      - password
      properties:
        account:
          type: string
          description: 帳號
          format: email
        password:
          type: string
          description: 密碼
      example:
        account: rammus
        password: 123123123

routes - 使用 $ref: '#/definitions/Admin'

###
#  tags: ["Auth"]
#  summary: 登入
#  parameters:
#    - name: body
#      description: account and password
#      schema:
#        $ref: '#/definitions/Admin'
###
POST    /login                      controllers.AuthController.login

definitions 用法 - 2

swagger.yml - 新增一個 AdminDefault 的物件

  definitions:
    Admin:
      type: object
      required:
      - account
      - password
      properties:
        account:
          type: string
          description: 帳號
          format: email
        password:
          type: string
          description: 密碼
      example:
        account: rammus
        password: 123123123
    AdminDefault:
      allOf:
      - $ref: '#/definitions/Admin'
      - type: object
        required:
        - name
        properties:
          name:
            type: string
            description: 商家品牌名稱
      example:
        account: rammus.xu
        password: 123123123
        name: Rammus Shop

這邊使用 allOf 來繼承 Admin

      allOf:
      - $ref: '#/definitions/Admin'

routes - 使用 $ref: '#/definitions/AdminDefault'

###
#  tags: ["Admin"]
#  summary: 新增Admin
#  parameters:
#    - name: body
#      schema:
#        $ref: '#/definitions/AdminDefault'
###
POST    /admin                      controllers.api.AdminController.createAdmin

More info: http://swagger.io/specification/#definitionsObject

[RammusXu]

http://rammusxu.github.io/2016/11/17/swagger-snippets/