rest - 原始类型的 Swagger 定义

Question

是否可以为原始类型定义 swagger 定义/模型？例如，考虑以下内容

definitions:
  program_name:
    type: string
    description: Unique string id

但是，上面的例子返回了很多错误(例如 swagger 需要一个 properties 字段)并且没有例子使用任何不是 type: object 的定义。

目的是将其用作另一个模型的子组件和参数——以某种方式重用已定义的组件。

把它想象成一个 swagger typedef

编辑:根据规范，定义对象与架构对象相同http://swagger.io/specification/#schemaObject ，声明它可以接受原始类型。

此外，假设原始类型可以存在于定义部分，简单参数类型(查询、路径等)是否可以引用原始定义类型？

Answer 1

您的示例中的原始模式是有效的，并且可以在任何需要模式对象的情况下使用，例如，作为另一个模式的子组件:

definitions:
  Program:
    type: object
    properties:
      program_name:
        $ref: "#/definitions/program_name"

  # This becomes:
  # type: object
  # properties:
  #   program_name:
  #     type: string
  #     description: Unique string id

或作为操作体参数或响应模式:

paths:
  /something:
    post:
      summary: POSTs and returns a string
      parameters:
        - in: body
          name: program_name
          schema:
            $ref: "#/definitions/program_name"
      responses:
        "200":
           description: OK
           schema:
             $ref: "#/definitions/program_name"

但是，简单的参数 - 路径、查询、标题和表单 - 不要使用 schema 关键字(它们使用 type 代替)因此它们不能引用来自 定义。

这将在下一版本 OpenAPI 3.0 中更改，其中 schema 将用于 all parameter types .