在 Play Framework 開發 swagger.io 的範例

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