Swagger YAML 声明中的子路径 [英] Subpaths in Swagger YAML declaration

问题描述

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

I am trying to create a REST service by describing it in Swagger YAML.

服务有三个路径:

• /版本
• /partners/{partnerId}/users/{userId}/sessions
• /partners/{partnerId}/books/{bookId}/

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

My current YAML file to describe these paths looks like this:

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"被声明了两次.

In this YAML file the parameter "partnerId" is declared twice.

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

Is there a way to make "subpaths" such that I don't have to declare the /partners/{partnerId} part of the path twice?

推荐答案

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

What you can do is declare the parameter at the top level, and then refer to it.

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

这篇关于Swagger YAML 声明中的子路径的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！