Question

We have a search page for an internal tool that users will use to search our recipes. This ends up being ~80 separate fields that may (or may not) be submitted to POST /search.

My question is, is there a better alternative to the Swagger documentation that listing every possible field? For instance, can I somehow reuse the recipe model definition that I reference as the return object in GET /recipes/{id}?

  '/recipes':
    get:
      summary: Retrieve a set of recipes.
      description: A paginated subset of recipes
      parameters:
        - in: query
          name: limit
          description: number of records returned
          required: false
          type: integer
          default: 50
        - in: query
          name: offset
          description: starting record
          required: false
          type: integer
          default: 0
      tags:
        - Recipes
      responses:
        '200':
          description: a subset of recipes
          schema:
            type: array
            items:
              $ref: '#/definitions/Recipe'

Maybe there's no way around re-defining all these parameters in the following format, but I thought I'd ask:

 '/search':
    post:
      description: Robust recipe search
      parameters:
        - in: body
          name: id
          description: recipe id.
          required: false
          type: string
        - in: body
          name: title
          description: Recipe title
          required: false
          type: string
        - in: body
          name: ingredient
          description: Searches ingredients for an exact match
          required: false
          type: string
        - in: body
          name: ingredientText
          description: Searches ingredients for a subString match
          required: false
          type: string
          ...

Answer 1

嗯，POST操作中不能有多个body参数。但是可以有多个formData参数。

我的问题是，如果你有非常多的非必填字段来提交搜索，或许你最好建模一个复杂的POST对象，它有每个标准的可选字段？然后，您定义了一个模式，用户可以通过输入他们想要使用的字段来输入他们想要的内容。

Shortcut for documenting large search API endpoint in Swagger?

1 个答案: