遵循REST规范的添加用户到组的OpenAPI描述规范咨询

一、HTTP方法选择 #

• POST是最优选择：你实际是在group和user之间创建关联关系，这种创建关联的操作完全符合POST的语义——用于执行非幂等的、创建资源（包括关联类资源）的操作。
  • 不选PUT：PUT是幂等操作，多用于全量更新资源（比如替换整个组的成员列表），和“添加单个用户”的场景不匹配。
  • 不选PATCH：PATCH用于对已有资源做部分属性更新（比如修改组名称），添加成员本质是创建新关联而非修改组本身，语义不符。
• 关于POST返回值：无需纠结“没有新实体ID返回”，可以返回201 Created状态码配合空响应体，或者返回更新后的组成员片段，甚至如果系统将用户组关联视为独立资源，也可以返回该关联的标识。

二、用户ID的传递方式 #

• 推荐放在请求体中：URL仅定位到目标资源集合（/groups/{id}/members），要添加的用户ID放在请求体更符合REST设计习惯，同时方便后续扩展（比如批量添加用户时，直接在请求体传ID数组即可）。
  • 如果把用户ID放在URL（如/groups/{id}/members/{userId}），更适合幂等性的PUT（重复添加无变化）或DELETE（移除用户）操作，和当前POST的语义适配性不强。

调整后的OpenAPI示例 #

paths:
  /groups/{id}/members:
    post:
      operationId: addUserToGroup
      summary: 添加用户到指定组
      parameters:
        - name: id
          required: true
          in: path
          schema:
            $ref: '#/components/schemas/ID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  $ref: '#/components/schemas/ID'
      responses:
        201:
          description: 用户成功加入组
        404:
          description: 组或用户不存在
        409:
          description: 用户已在组中

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