假设我有一个带有用户资源的REST API。有三种方法可以使用用户资源:POST
创建,GET
下载和PATCH
更改。所有方法都在相同的用户类型上运行,但具有不同的必需属性 - 使用POST
创建用户时,除了用户ID之外的所有请求字段都是必需的,使用GET
下载时,所有响应字段都是必填字段包括ID,使用PATCH
进行更改时,所有请求字段都是可选的,可以为空。
我可以在OpenAPI / Swagger中简单描述这个吗?我只想描述User类型一次,然后只说出每个方法需要/可空的字段。有点像这样,在伪代码中:
definitions:
User:
properties:
id:
type: integer
name:
type: string
…
paths:
/users
post:
request:
schema: User
required: [name, …]
nullable: […]
response:
schema: User
required: [id, name, …]
nullable: […]
/users/{id}:
get:
response:
schema: User
required: [id, name, …]
nullable: […]
patch:
request:
schema: User
required: []
nullable: [name, …]
这样我就不必重复所有字段定义,同时具有针对每种方法描述的特定约束。那可能吗?它有意义吗?