Vary presence and requirement of properties with CRUD operation

Đang mở
#1,497 21 bình luận 10 reaction 0 người được giao Xem trên GitHub

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
25/100
Loại issue
Tính năng
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Đình trệ
Công nghệ
openapi
Lĩnh vực
api

Hướng nghiên cứu

Bắt đầu bằng việc xem xét bảng vendor-extension của issue cùng với ngữ nghĩa OpenAPI hiện có cho readOnly, writeOnly và required. Công việc được xem là hoàn tất khi có một đặc tả đã được thống nhất về sự hiện diện và các yêu cầu của property phụ thuộc vào CRUD, bao gồm các quy tắc xác thực và tương tác với composition và các schema đa hình.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

schema-object

Properties of a schema could be marked as readOnly or writeOnly if they should not be used respectively in a request or response. Additionally, required properties are present in the required field. Request vs response is the only criteria that can alter a resource schema.

This was not sufficient to describe our legacy REST APIs where presence and requirement of resource's properties is highly dependent of CRUD operation. The was due, in part, to wrong design choices. However, we faced generic situations that cannot be expressed for example:

  • Write once / immutable property: for properties like slug or identifier. Those properties should not be part of update request.
  • Server side default value: this kind of property is required only in response.

All this can be achieved using composition. I don't think that's a reasonable solution because:

  • contract is not more human readable as resources are split in many schema
  • for polymorphic resources (using oneOf), there is too many different schema to create and duplication is inevitable

We used following vendor extensions to be able to produce the documentation of our API:

Field Name Type Description
x-createOnly boolean Relevant only for Schema "properties" definitions. Declares the property as "create only". This means that it MAY be sent as part of a POST request but SHOULD NOT be sent as part of the response or any other request type. If the property is marked as x-createOnly being true and is in the required list, the required will take effect on the POST request only. A property MUST NOT be marked as both x-createOnly and readOnly, writeOnly, x-updateOnly, x-createForbidden or x-updateForbidden being true. Default value is false.
x-updateOnly boolean Relevant only for Schema "properties" definitions. Declares the property as "update only". This means that it MAY be sent as part of a PUT request but SHOULD NOT be sent as part of the response or any other request type. If the property is marked as x-updateOnly being true and is in the required list, the required will take effect on the PUT request only. A property MUST NOT be marked as both x-updateOnly and readOnly, writeOnly, x-createOnly, x-createForbidden or x-updateForbidden being true. Default value is false.
x-createForbidden boolean Relevant only for Schema "properties" definitions. Declares the property as "create forbidden". This means that it MAY be sent as part of a PUT request or be sent as part of the response but SHOULD NOT be sent as part of any other request type. If the property is marked as x-createForbidden being true and is in the required list, the required will take effect on the PUT request and the response only. A property MUST NOT be marked as both x-createForbidden and readOnly, writeOnly, x-createOnly, x-updateOnly or x-updateForbidden being true. Default value is false.
x-updateForbidden boolean Relevant only for Schema "properties" definitions. Declares the property as "create and read only". This means that it MAY be sent as part of a POST request or be sent as part of the response but SHOULD NOT be sent as part of any other request type. If the property is marked as x-updateForbidden being true and is in the required list, the required will take effect on the POST request and the response only. A property MUST NOT be marked as both x-updateForbidden and readOnly, writeOnly, x-createOnly, x-updateOnly or x-createForbidden being true. Default value is false.
x-requiredCreate [string] List properties required in the POST request.
x-requiredUpdate [string] List properties requires in the PUT request.
x-requiredRead [string] List properties required in the response.

Being able to describe requirement and presence of resource's properties based on usage context could be a great enhancement.

Ngôn ngữ chính
Markdown
Star
31.2k
Fork
9.2k
Merge trung bình
6 giờ 37 phút
Pull request đã merge (30 ngày)
27

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của OAI/OpenAPI-Specification

Tất cả issue của OAI/OpenAPI-Specification

Issue tương tự

Thêm issue về Backend & API Design

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.