如何记录OpenAPI中的JSON合并补丁端点？

Question

我已经实施了通过OpenAPI记录的REST API。详细说明，该规范是使用SpringDoc-Openapi从Java源代码生成的。

但是，我需要接受补丁。因此，我

  /customers/{id}:
    patch:
      tags:
        - Customers
      summary: Updates an existing user
      description: Updates an existing user
      operationId: partialUpdateMergePatchCustomer
      parameters:
        - name: id
          in: path
          description: The numeric ID of the customer
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        content:
          application/merge-patch+json:
            schema:
              type: object
        required: true

已经阅读了OpenAPI规范/文档，但没有找到有关JSON MERGE补丁，JSON补丁等的任何信息。

我正在遇到以下我想克服的问题：

1. 在这里要修补哪种类型的资源。其余的API，特别是。在Swaggerui中，有充分的文献记载，并且到处都有模式参考。如何指定实际要修补的资源模式？
2. 除了纯模式参考，在我的API中，一些资源具有仅阅读字段，或者可能还适用于我想记录的某些字段的其他限制。作为原始架构的一部分，用自然语言做它有更好的方法吗？

Answer 1

我的问题与您的第1期相同。也就是说，与SpringDoc-Openapi生成的默认值相比，提供更多的信息来宣传JSONPATCH请求Boby参数。我将在此处发布可能会遇到同一问题的其他人的解决方案。

我的解决方案是将以下注释添加到RestController补丁方法：

@PatchMapping(value = "/{id}", consumes = "application/json-patch+json")
@io.swagger.v3.oas.annotations.parameters.RequestBody(content = @Content(array = @ArraySchema(schema = @Schema(implementation = JsonPatchSchema.class))))
    public void patch(@PathVariable @Min(0) long id, @RequestBody JsonPatch patch) {

其中JSONPATCHSCHEMA包含请求的格式：

public class JsonPatchSchema {
    @NotBlank
    public Op op;

    public enum Op {
        replace, add, remove, copy, move, test
    }

    @NotBlank
    @Schema(example = "/name")
    public String path;

    @NotBlank
    public String value;
}

使用@schema注释您可以提供有关允许的内容的更多详细信息，请参见。例如，模式参数允许您定义正则表达式。不幸的是，我还没有找到一种生成允许内容的方法。