Swagger YAML配置新增createdOn、completedOn字段后输出异常咨询

错误原因排查 #

1. YAML语法对缩进要求极其严格，新增的createdOn、completedOn字段缩进层级和所属父节点不匹配，会直接导致Swagger解析失败
2. 同层级key重复冲突：当前viewHealthWorkerDto对象的属性中已经存在createdOn字段定义，如果在同一层级重复定义相同key，会直接触发YAML解析异常
3. 字段所属层级不清晰：未明确新增字段属于外层邀请Dto还是内部健康工作者Dto，放错位置也会导致接口输出异常

正确配置方案 #

根据常用业务场景，分两种实现方式可选：

场景1：新增字段属于外层ViewInvitationDto（和viewHealthWorkerDto平级，适用于记录邀请本身的创建/完成时间） #

将字段放到items.properties节点下，保证缩进和viewHealthWorkerDto完全对齐即可。

场景2：新增字段属于内部viewHealthWorkerDto（和invitationCompletedOn平级，适用于记录健康工作者相关的时间） #

需要先将新增的createdOn改名避免和现有字段冲突（比如改为invitationCreatedOn），再保证缩进和invitationCompletedOn完全一致。

完整正确配置示例（按场景1实现） #

/**
* @openapi
* /api/v2/organizations/:organizationId/invitations:
*   get:
*     description: 获取数据访问对象邀请列表
*     responses:
*       200:
*         description: 获取数据访问对象邀请列表成功
*         content:
*           application/json:
*             schema:
*               type: object
*               properties:
*                 data:
*                   type: array
*                   items:
*                     type: object
*                     properties:
*                       _type:
*                         type: string
*                         description: 新邀请的数据传输对象
*                         example: ViewInvitationDto
*                       email:
*                         type: string
*                         description: 邀请邮箱
*                         example: dolittle@qa.co
*                       pui:
*                         type: string
*                         description: 患者用户ID
*                         example: spyrt_p10102acc
*                       groupId:
*                         type: string
*                         description: 机构标识
*                         example: poi_5002
*                       roleDescription:
*                         type: string
*                         description: 机构角色
*                         example: admin
*                       # 新增的两个字段放在外层邀请Dto下
*                       createdOn:
*                         type: string
*                         example: 2021-09-22T08:27:49.622Z
*                       completedOn:
*                         type: string
*                         example: 2021-09-22T08:27:49.622Z
*                       viewHealthWorkerDto:
*                         type: object
*                         properties:
*                           _type:
*                             type: string
*                             description: 健康工作者数据访问对象
*                             example: ViewHealthWorkerDto
*                           _id:
*                             type: string
*                             description: 健康工作者标识
*                             example: 613ef0964b525196cf8599bf
*                           assignedRoleCode:
*                             type: string
*                             description: 机构和健康工作者的分配角色编码
*                             example: armada.organization.doctor
*                           pui:
*                             type: string
*                             description: 机构和健康工作者的分配角色编码
*                             example: spyrt_p10102acc
*                           firstName:
*                             type: string
*                             description: 健康工作者名字
*                             example: John
*                           lastName:
*                             type: string
*                             description: 健康工作者姓氏
*                             example: Dolittle
*                           healthWorkerTags:
*                               example:
*                                 - key: migratedOn
*                                   value: 2021-11-19T00:00:43.722Z
*                                 - key: exporterVersion
*                                   value: 2
*                                 - key: _oldAccountId
*                                   value: 10102
*                                 - key: _oldPatientIds
*                                   value: 10729
*                           schemaVersion:
*                             type: string
*                             example: 1
*                           createdOn:
*                             type: string
*                             example: 2020-05-08T07:43:43.000Z
*                           updatedOn:
*                             type: string
*                             example: 2020-05-08T07:43:43.000Z
*                           roleDescription:
*                             type: string
*                             example: admin
*                           email:
*                             type: string
*                             example: dolitle@qa.co
*                           userTags:
*                               example:
*                                 - key: migratedOn
*                                   value: 2021-11-19T00:00:43.722Z
*                                 - key: exporterVersion
*                                   value: 2
*                                 - key: _oldAccountId
*                                   value: 10102
*                                 - key: _oldPatientIds
*                                   value: 10729
*                           invitationCompletedOn:
*                             type: string
*                             example: 2021-09-22T08:27:49.622Z
*
*
*/

内容的提问来源于stack exchange，提问作者Daniel