Java 如何手动记录JAX-RS参数的Swagger数据模型？ 上下文

假设我有一个简单的Java数据类：

公共类人物{
私有最终字符串名；
私人最终年龄；
Person（字符串名称，整数年龄）{
this.name=名称；
这个。年龄=年龄；
}
公共字符串getName（）{
返回名称；
}
int字符串getAge（）{
回归年龄；
}
}

注意：在实践中，我使用生成这个，但是为了简单起见，我在这里显示了一个

要记录

GET

响应的模型，即使返回类型是

response

，我也可以参考以下内容中的类：

@GET
@ApiOperation（响应=Person.class）
公众回应{
返回Response.ok（newperson（“Julien”，28））.build（）；
}

基于此，斯威格将正确记录以下内容：

型号：

Person {
  name (string),
  age (number)
}

JsonNode {
  array (boolean, optional),
  null (boolean, optional),
  number (boolean, optional),
  float (boolean, optional),
  pojo (boolean, optional),
  valueNode (boolean, optional),
  containerNode (boolean, optional),
  object (boolean, optional),
  missingNode (boolean, optional),
  nodeType (string, optional) = ['ARRAY', 'BINARY', 'BOOLEAN', 'MISSING', 'NULL', 'NUMBER', 'OBJECT', 'POJO', 'STRING'],
  integralNumber (boolean, optional),
  floatingPointNumber (boolean, optional),
  short (boolean, optional),
  int (boolean, optional),
  long (boolean, optional),
  double (boolean, optional),
  bigDecimal (boolean, optional),
  bigInteger (boolean, optional),
  textual (boolean, optional),
  boolean (boolean, optional),
  binary (boolean, optional)
}

示例值：

{
  "name": "string",
  "age": 0
}

{
  "array": true,
  "null": true,
  "number": true,
  "float": true,
  "pojo": true,
  "valueNode": true,
  "containerNode": true,
  "object": true,
  "missingNode": true,
  "nodeType": "ARRAY",
  "integralNumber": true,
  "floatingPointNumber": true,
  "short": true,
  "int": true,
  "long": true,
  "double": true,
  "bigDecimal": true,
  "bigInteger": true,
  "textual": true,
  "boolean": true,
  "binary": true
}

为了记录

POST

主体的模型，我直接在代码中使用类，Swagger找到它并根据需要记录它：

@POST
@ApiOperation（响应=Person.class）
公共响应addPerson（Person newPerson）{
返回Response.ok（store.insert（newPerson））.build（）；
}

问题 我想支持部分更新以及。我不能使用POJO本身，因为POJO中的所有字段都是必需的，所以当无效JSON被发送到例如

POST

方法时，我依靠它来获得安全检查并清除错误消息

在我的实际用例中，我的数据模型包含映射。我希望用户能够在更新中指定某个键，并将该值设置为

null

，以从现有映射中删除元素

我选择支持

PATCH

请求，其中正文被键入为普通的

JsonNode

。这允许我的服务器接收任何JSON，我可以根据自己的意愿应用更新

@补丁
@路径（“/{name}”）
@ApiOperation（响应=Person.class）
公共响应更新person（@PathParam（“name”）字符串名称，JsonNode更新）{
返回Response.ok（store.update（name，update））.build（）；
}

我对结果很满意，除了Swagger现在用

JsonNode

Java对象的属性记录了部分更新的模型：

型号：

Person {
  name (string),
  age (number)
}

JsonNode {
  array (boolean, optional),
  null (boolean, optional),
  number (boolean, optional),
  float (boolean, optional),
  pojo (boolean, optional),
  valueNode (boolean, optional),
  containerNode (boolean, optional),
  object (boolean, optional),
  missingNode (boolean, optional),
  nodeType (string, optional) = ['ARRAY', 'BINARY', 'BOOLEAN', 'MISSING', 'NULL', 'NUMBER', 'OBJECT', 'POJO', 'STRING'],
  integralNumber (boolean, optional),
  floatingPointNumber (boolean, optional),
  short (boolean, optional),
  int (boolean, optional),
  long (boolean, optional),
  double (boolean, optional),
  bigDecimal (boolean, optional),
  bigInteger (boolean, optional),
  textual (boolean, optional),
  boolean (boolean, optional),
  binary (boolean, optional)
}

示例值：

{
  "name": "string",
  "age": 0
}

{
  "array": true,
  "null": true,
  "number": true,
  "float": true,
  "pojo": true,
  "valueNode": true,
  "containerNode": true,
  "object": true,
  "missingNode": true,
  "nodeType": "ARRAY",
  "integralNumber": true,
  "floatingPointNumber": true,
  "short": true,
  "int": true,
  "long": true,
  "double": true,
  "bigDecimal": true,
  "bigInteger": true,
  "textual": true,
  "boolean": true,
  "binary": true
}

我想在我的代码中指定模型类似于

Person

，以便在Swagger UI中给出的示例更加相关。我确实尝试了

@apimplicitparams

：

@补丁
@路径（“/{name}”）
@ApiOperation（响应=Person.class）
@ApitParams({
@apimplicitparam（name=“update”，dataTypeClass=Person.class）
})
公共响应更新person（@PathParam（“name”）字符串名称，JsonNode更新）{
返回Response.ok（store.update（name，update））.build（）；
}

这没有任何区别。斯威格仍然记录着

JsonNode

本身。文件中提到：

虽然绑定到JAX-RS参数、方法或字段，但这允许您以微调方式手动定义参数。这是使用servlet或其他非JAX-RS环境时定义参数的唯一方法

由于我使用的是JAX-RS，这可能意味着我不能使用

@apimplicitparams

，但不提供任何重写类的内容

---

如何手动指定Swagger自动检测到的JAX-RS参数的数据模型？

我使用

@apimplicitparam

的方法是正确的，我想我已经按照我想要的方式工作了，现在：

@补丁
@路径（“/{name}”）
@ApiOperation（响应=Person.class）
@ApitParams({
@apimplicitParam（paramType=“body”，dataTypeClass=ExchangeConfiguration.class）
})
公共响应更新person（@PathParam（“name”）字符串名称，@ApiParam（hidden=true）JsonNode更新）{
返回Response.ok（store.update（name，update））.build（）；
}

配置名称不是强制性的，但似乎需要

paramType

。使用

paramType=“body”

可以使Swagger正确地记录隐式参数。这将导致尸体被记录两次；我们可以使用

@ApiParam（hidden=true）

隐藏使用错误模型自动生成的版本

使用上面的代码，文档看起来完全符合我的要求，代码继续正确运行

---

谢谢大家的帮助

为了更好地理解

@apimplicitparams

，添加此答案，使其具有某种通用性

您必须使用

@apimplicitparams

包装要保存在文档中的参数。

@apimplicitparam

有许多不太明显的好处，比如传入额外的头参数而不将其添加为方法参数，或者在您的情况下包装参数以使其具有某种意义

对于您的问题，您必须使用

@apimplicitparam

以及

paramType=“body”

来更改正文，同样，如果您希望更改标头，则必须使用

paramType=“head”

您还可以使用属性

required=true/false

控制

@apimplicitparam

中的必填字段

如前所述，您可以传递一个参数，而不必在方法param中使用它，您可以使用属性

value=“required value”

控制它的值

---

您还可以使用逗号分隔的值控制

@apimplicitparam

中的允许值。例如，

allowableValues=“无缓存，无存储”

“将正文键入为普通JsonNode的补丁请求”。你为什么这么做？为什么不使用

Person

？@LutzHorn

Person

被注释，因此所有字段都是必填字段。我依赖于此，以便在向例如

POST

方法等提供无效JSON时，获得安全检查并清除错误消息。

JsonNode

在我的玩具示例中不可见的另一个优点是