Swagger：REST API中的自定义操作

Question

在我们的REST API项目中，我们发现一个支持多个自定义操作的REST API有点困难。

可以对此资源执行多个操作，例如VALIDATE，PROCESS等。数据不会保留在后端，而是规则引擎（在后端）会对资源执行这些操作并返回结果。

REST URI：PUT http://<hostnam>:<port>/<context-root>/rest/configuration

身体：

{
     "action": "VALIDATE",
     "commonAttribute": "",
     "validateAttribute": ""
}

或

{
     "action": "PROCESS",
     "commonAttribute": "",
     "processAttribute": ""
}

对于VALIDATE操作，提供了公共属性和特定于验证的属性（validateAttribute）。与PROCESS行动类似。

创建配置POJO以按以下方式表示输入：

public class Configuration {
    // will be modeled as enum
    private String action;

    private String commonAttribute;
    private String validateAttribute;
    private String processAttribute;

    // getters and setters
}

由于这两个操作是在单个REST URI中实现的，因此swagger文档变得稍微复杂一些。在此URI下，请求正文的model schema将同时包含validateAttribute和processAttribute，如下所示：

{
    "action": "string",
    "commonAttribute": "string",
    "validateAttribute": "string",
    "processAttribute": "string"
}

这两个属性的存在会给用户带来某种混淆，即使 - 虽然详细的细节，例如哪个属性为哪个动作可以在口头文档（swagger）中涵盖。

注1 ：根据REST设计指南，这些操作未包含在REST URI路径中。 注意2 ：PUT操作是在POST上选择的，因为我们的操作本质上是幂等的。

我正在寻找指导，以极其简洁的方式在swagger doc中表示这些行为及其属性。是否有更好的方法来设计这些API或以夸张的方式表示它们。