开放 API 3.0.1 只读注解答案

【问题标题】：Open API 3.0.1 readOnly Annotation开放 API 3.0.1 只读注解
【发布时间】：2020-02-07 14:33:31
【问题描述】：

我在使用 Open API 3.0.1 java 注释来将属性定义为特定方法的 readOnly 时遇到一些问题。在POST 操作期间，API 需要一个NewAccount 模型。这是模型的截断表示；

{
    "user": {
        "id": "...",
        ...
    },
    "account": {
        "id": "...",
        ...
    }
}

我需要在此操作中将user.id 和account.id 定义为readOnly。我所有的文档都是通过注释从代码中生成的，这就是我目前所拥有的；

    @POST
    @Path("/access/accounts")
    @Consumes("application/json")
    @Operation(
            summary = "Create a new account.",
            description = "Create a new account."
    )
    @Tags({@Tag(name = "account")})
    @RequestBody(
            description = "New accounts required models.",
            required = true,
            content = @Content(
                    schema = @Schema(
                            implementation = NewAccount.class
                    )
            )
    )
    @ApiResponses({
            @ApiResponse(
                    responseCode = "201",
                    description = "The new account.",
                    content = @Content(
                            schema = @Schema(
                                    implementation = Account.class
                            )
                    )
            )
    })

【问题讨论】：

你能同时发布Account 和NewAccount 课程吗？具体来说，id 属性是如何定义和注释的。
它们没有注释。注释特定于该方法，因此我需要在每个相应的方法中定义它。但是，它们只是字符串值。
关于此的任何信息。在使用 Micronaut 的 Kotlin 中，这对我也不起作用

标签： java annotations swagger openapi

【解决方案1】：

您需要将@Schema(accessMode = Schema.AccessMode.READ_ONLY) 注释添加到id 属性。这将在生成的 OpenAPI 定义中将id 属性标记为readOnly: true。

例如from here:

import io.swagger.v3.oas.annotations.media.Schema;

public class ReadOnlyFields {
    @Schema(accessMode = Schema.AccessMode.READ_ONLY)
    public Long id;
}

【讨论】：

但这会将其标记为永久readOnly。我想要实现的是将其标记为readOnly，仅针对这个特定的POST。如果我希望它始终为readOnly，您的注释绝对正确。在我的@Schema 定义中，应该有一种方法可以为我可以定义的特定属性添加accessMode。