如何使用 OpenAPI 规范保持单一资源表示方法 [英] How to keep the single resource representation approach using OpenAPI spec

问题描述

阅读此post(参见:3 How to use a single definition when...)关于使用 OpenAPI 描述 REST API(Swagger) 规范，您可以注意如何使用 readOnly 属性保留单个资源表示来添加/更新和获取资源，而不是使用一种表示来获取(获取集合项)和另一种表示用于添加(POST 到一个集合).例如，在下面的 User 单一表示中，id 是一个只读属性，这意味着它不会在创建用户时在表示中发送，它会在用户创建时发送已检索.

Reading this post (see: 3 How to use a single definition when...) about describing a REST API using OpenAPI (Swagger) specification you can note how to keep a single resource representation for adding/updating and getting resource using readOnly property instead of having one representation for getting (GET a collection item) and other one for adding (POST to a collection). For example, in the following User single representation, the id is a read-only property which mean that it won't be sent in the representation when a user is created, it will be there when a user is retrieved.

"User":
{
    "type": "object",
    "properties": {
        "id": {
            "type": "integer",
            "format": "int64",
            "readOnly": true
        },
        "company_data": {
            "type": "object",
            "properties": {
                .
                .
                .
            },
            "readOnly": false
        }
    }
}

保持资源表示列表尽可能短真的很干净而且很好，所以我想保持单一资源表示方法，但我面临的问题是:如何管理必需 当一个属性是强制输入时?假设我需要在创建用户时根据需要设置 company_data (POST/users/)，但在检索用户时不需要设置 (GET/users/{user_id}).OpenAPI 规范中有什么方法可以在不丢失单一资源表示的情况下满足这种需求?

It is really clean and nice to keep the list of resource representation as short as possible so I want to keep the single resource representation approach but the problem I am facing to do that is: how to manage required when a property is mandatory for input only? Suppose I need to set company_data as required when the user is created (POST /users/) but non-required when an user is retrieved (GET /users/{user_id}). There are any way in OpenAPI specification to satisfy this need without lost the single resource representation?

推荐答案

来自 Swagger-OpenAPI 2.0 spec，readonly定义如下:

From the Swagger-OpenAPI 2.0 spec, readonly is defined as follows:

将属性声明为只读".这意味着它可以被发送作为响应的一部分，但不得作为请求的一部分发送.标记为 readOnly 的属性为 true 不应该在 required已定义架构的列表.默认值为 false.

Declares the property as "read only". This means that it MAY be sent as part of a response but MUST NOT be sent as part of the request. Properties marked as readOnly being true SHOULD NOT be in the required list of the defined schema. Default value is false.

由于规范说不应要求只读属性，因此 readonly + required 的含义没有定义语义.

Since the specification says that a read-only property should not be required, there are no defined semantics for what readonly + required should mean.

(按理说 readonly + required 表示它在响应中是必需的，但仍然从请求中排除.实际上有一个 open issue 进行此更改，看起来它正在考虑 OpenAPI 3.0.)

(It might have been reasonable to say that readonly + required means it's required in the response, but still excluded from the request. In fact there is an open issue to make this change, and it looks like it's under consideration for OpenAPI 3.0.)

不幸的是，单个架构无法在请求中设置属性，但在响应中是可选的(或不允许的).

Unfortunately there is no way for a single schema to make properties required in the request, but optional (or disallowed) in the response.

(同样，有一个 未决问题提出只写" 修饰符，可能正在考虑下一个版本.)

(Again, there's an open issue proposing a "write-only" modifier, possibly under consideration for the next release.)

目前，您需要为这些不同的情况创建不同的架构.正如这里描述的，您也许可以制作这些架构多一点 DRY 使用 allOf 组合.

For now, you would need to create different schemas for these different cases. As described here, you might be able to make these schemas a bit more DRY using allOf composition.

这篇关于如何使用 OpenAPI 规范保持单一资源表示方法的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！