OpenAPI：强制字段、可选字段和未指定字段的混合

Question

例如，endpoint/user

user_id: str, mandatory
timestamp_utc: timestamp, optional
..*accept_any_extra_fields**..

因此，如果有人将以下json发送到我的endpoint，endpoint应该接受它

{ "user_id": 1,
  "name": "Sam",
  "location": "USA"
}

但如果发送以下json，则失败，因为它不包含user_id。

{ "name": "Sam",
  "location": "USA"
}

Answer 1

您使用Java-Spring吗？我在Spring控制器中使用了注释方法中的Swagger，在java代码中，您可以以这种方式指定所需的params：

@ApiOperation(value = "Get user", notes = "Get a user by the given filters")
@GetMapping("v1/users")
public UserDTO getUsers(@ApiParam(value = "User id", required = true)
                        @RequestParam(value = "user_id", required = true) String userId,

                        @ApiParam(value = "Date", required = false)
                        @RequestParam(value = "timestamp_utc", required = false) 
                        @DateTimeFormat(iso = DateTimeFormat.ISO.DATE_TIME) LocalDateTime utc,

                        @ApiParam(value = "Some other", required = false)
                        @RequestParam(value = "some_other", required = false) String someOther){

             return service.getUser(userId, utc, someOther);
      }

注释@apiOperation用于描述Endpint。

注释@apiparam用于描述param特征，所需的属性用于通知这一点。