如何在OpenAPI 3.0中用两个可选参数定义路径?

Posted

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了如何在OpenAPI 3.0中用两个可选参数定义路径?相关的知识,希望对你有一定的参考价值。

我在SwaggerHub注册并使用OpenAPI 3.0创建了新的API。在我的API中,/tasks路径具有2个非必需参数,但我无法将其设置为非必需参数-编辑器显示“不允许的值”错误。

这是我的API定义:

openapi: 3.0.0
info:
  description: A Simple IP Address API
  title: VTasks
  version: v1
servers:
# Added by API Auto Mocking Plugin
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/petrogromovo/Vtasks/1.0.0
  - description: SwaggerHub API Auto Mocking
    url: http://hosting.tk

paths:

  /tasks:
    get:
      tags:
        - tasks
      summary: Get paginated / filtered tasks listing
      operationId: tasks
      parameters:
        - name: page
          in: path
          description: The page number to be fetched. If missed default 1.
          required: true
          schema:
            type: integer
        - name: order_by
          in: path
          description: The order_by  be fetched. 
          required: false  // ERROR : should be equal to one of the allowed values allowedValues: true
          schema:
            type: string
        - name: filter
          in: path
          description: The filter for title field. 
          required: false // ERROR : should be equal to one of the allowed values allowedValues: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
        '400':
          description: Invalid tasks supplied
        '404':
          description: tasks were not found

但是如果删除required属性,则会出现2个错误:

[应具有必需的属性”missingProperty:必填

有效语法是什么?

答案

这些参数应该是路径参数还是查询参数?

路径参数in: path)是端点路径的一部分,因此必须在路径模板中由{...}表示:

paths:
  /tasks/{page}/{order_by}/{filter}:

始终需要路径参数,即它们必须具有required: true

Query parameters在查询字符串中发送,例如/tasks?page=...&order_by=...。要使用查询参数,请将参数位置更改为in: query

以上是关于如何在OpenAPI 3.0中用两个可选参数定义路径?的主要内容,如果未能解决你的问题,请参考以下文章

如何在 Gradle 中为 OpenAPI 3.0 使用 Swagger Codegen?

如何使用 Springdoc 在 OpenAPI 3.0 中创建链接?

如何从 OpenAPI 3.0 生成 PDF 或标记?

如何在 OpenAPI (Swagger) 中为同一路径定义不同的查询参数?

Java - 如何直接从 openapi 3.0 规范生成 Swagger UI

如何使用 swagger 在路径中定义可选参数