如何使用OpenAPI规范保留单一资源表示方法

问题描述

阅读此发布(请参阅: 3如何在...时使用单个定义... )有关使用OpenAPI描述REST API的说明(Swagger) )规范，您可以注意到如何使用 readOnly 属性保留一个用于添加/更新和获取资源的单一资源表示形式，而不是使用一种表示形式来获取(获取集合项)，而使用另一种表示形式来添加(POST到)集合).例如，在以下用户单一表示形式中， 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
        }
    }
}

使资源表示形式的列表尽可能短是非常干净和不错的，因此我想保持单一资源表示方式，但是我要解决的问题是:如何管理必需的当仅输入必需的属性时?假设我需要在创建用户(POST/users/)时根据需要设置 company_data ，但在检索用户(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规范，readonly的定义如下:

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

由于该规范说不需要只读属性，因此对于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表示它是响应中必需的，但仍被排除在请求之外.实际上，有一个未解决的问题进行此更改，并且似乎正在考虑 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.)

就目前而言，您需要针对这些不同的情况创建不同的架构.正如此处所述，您可能能够创建这些架构使用allOf组合 DRY .

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规范保留单一资源表示方法的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持！