添加基于模式的示例

Question

说我有一个描述API调用返回值的架构。该架构包含具有自己的架构的复杂对象，例如：名为“接口”的对象。有没有一种方法可以使UI敏捷地根据接口模式为“接口”字段生成示例？

interfaces:
  description: A list of the device's interfaces
  type: array
  items:
    type: object
    required: true
    schema: 
      $ref: '#components/schemas/Interface'
    example: #<---- What should I put here?
  required: true

Interface:
  type: object
  properties:
    name:
      description: Interface's name
      type: string
      required: true
      example: eth0
    IP:
     ...

Answer 1

在示例中，您应该放置基本变量或对象的期望值。例如，如果USERNAME变量类型为字符串，则示例可能为“ exampleuser190”。如果ID是整数类型，则示例可能是“ 845”或类似。可以由示例决定，但是请尝试精确一些，以表示API中的实际情况和变量结构。

因此，如果期望值的长度为12位，并且前面有两个零，则不要使用简单的示例作为“ 5”，例如一个“ 003454534546”或用户名的某些复杂键，等等。

在您的情况下，我会将示例放到Interfaces模式中或将预期的对象放到示例中（看起来如何）：

interfaces:
  description: A list of the device's interfaces
  type: array
  items:
    type: object
    required: true
    schema: 
      $ref: '#components/schemas/Interface'
  required: true

components:
  schemas:
   Interface:
     variableXX:
       type: integer
       example: 34534

Answer 2

通读文档后，似乎OpenAPI 3.0支持常见示例的定义，这些示例可以在API文档yaml文件中重复使用。请参见以下link的“重用示例”部分中的示例。