Swagger YAML声明中的子路径

Question

我试图通过在Swagger YAML中描述它来创建REST服务.

该服务有三条路径:

• /版本
• /合作伙伴/ {} PARTNERID /用户/ {} userId的/会话
• /合作伙伴/ {} PARTNERID /书籍/ {} BOOKID /

我当前描述这些路径的YAML文件如下所示:

swagger: '2.0'
info:
  version: '0.0.1'
  title: Test API
host: api.test.com
basePath: /
schemes:
  - https
consumes:
  - application/json
produces:
  - application/json
paths:
  /versions:
    post:
      responses:
        '201':
          description: Returns all versions.
        default:
          description: unexpected error
  /partners/{partnerId}/users/{userId}/sessions:
    parameters:
      - name: partnerId
        in: path
        type: integer
      - name: userId
        in: path
        type: string
    post:
      responses:
        '201':
          description: Returns a UserSession object with info about the user session.
        default:
          description: unexpected error
  /partners/{partnerId}/books/{bookId}/:
    parameters:
      - name: partnerId
        in: path
        type: integer
      - name: bookId
        in: path
        type: string
    get:
      responses:
        '200':
          description: Gets a book.
        default:
          description: unexpected error

在此YAML文件中,参数"partnerId"被声明两次.

有没有办法制作"子路径",这样我就不必/partners/{partnerId}两次声明路径的一部分了？

Answer 1

你可以做的是在顶层声明参数,然后引用它.

swagger: '2.0'
info:
  version: '0.0.1'
  title: Test API
host: api.test.com
basePath: /
schemes:
  - https
consumes:
  - application/json
produces:
  - application/json
parameters:
  partnerId:
    name: partnerId
    in: path
    type: integer
paths:
  /versions:
    post:
      responses:
        '201':
          description: Returns all versions.
        default:
          description: unexpected error
  /partners/{partnerId}/users/{userId}/sessions:
    parameters:
      - $ref: '#/parameters/partnerId'
      - name: userId
        in: path
        type: string
    post:
      responses:
        '201':
          description: Returns a UserSession object with info about the user session.
        default:
          description: unexpected error
  /partners/{partnerId}/books/{bookId}/:
    parameters:
      - $ref: '#/parameters/partnerId'
      - name: bookId
        in: path
        type: string
    get:
      responses:
        '200':
          description: Gets a book.
        default:
          description: unexpected error