API 蓝图中的自定义操作名称

Question

我正在尝试编写一个 API，并努力寻找一种向资源添加自定义操作的好方法。例如，在我的用户资源中，我希望拥有enabled 和disable 操作，但在通常的蓝图分组中，我无法将它们添加到组下：

## User [/users/{id}]

### Update a User [PATCH]
    ...

### Delete a User [DELETE]
    ...

### Disable a User [PATCH]
    ....

在这里，Disable a User 和 Update a User 都指向同一个 URL，这不是我想要的。我希望这些分别生成 URL /users/{id} 和 /users/{id}/disable。

查看其他 API 源，其他人在不使用命名资源的情况下完成了它，这将给出：

## /users/{id}

    ### Update a User [PATCH]
        ...

    ### Delete a User [DELETE]
        ...

## /users/{id}/disable

    ### Disable a User [PATCH]
        ...

虽然我可以使用这种方法，但我更喜欢使用第一种方法，因为它在被大多数蓝图工具渲染时更清晰。

有没有一种方法可以使用第一种方法进行自定义操作，或者其他人有没有更简洁的方法来实现相同的东西

Answer 1

在这个例子中，因为有两个不同的 URL，你实际上会得到两个不同的资源。一种资源是用户资源，而另一种是禁用用户资源。要在您的 API 蓝图中组织这些资源，您可以将这些资源与 Resource Group 组合在一起。

# Group User Resources

## User [/users/{id}]

### Update a User [PATCH]
    ...

### Delete a User [DELETE]
    ...

## Disable User [/users/{id}/disable]

### Disable User [PATCH]
    ...

这允许您对单独的 URL 执行单独的操作，同时将它们捆绑在您的文档中。