[RFC] Handle OpenAPI 3.1 BC Breaks
- Ngôn ngữ chính
- PHP
- Star
- 500
- Fork
- 99
- Chỉ số merge pull request
- Không có pull request nào được merge trong 30 ngày
Mô tả
It's nice to see the work for the OpenAPI 3.1 standard. I think a big part are the deprecated fields or type changes like:
- The nullable keyword has been removed from the Schema Object (null can be used as a type value).
- the type can be now an array with the type and `null`
- exclusiveMaximum and exclusiveMinimum cannot accept boolean values (following JSON Schema).
- See more at [Stoplight Blog](https://blog.stoplight.io/difference-between-open-v2-v3-v31) and [OpenAPI Release Notes](https://github.com/OAI/OpenAPI-Specification/releases/tag/3.1.0-rc0)
How would you like to handle these breaking changes?
My first idea was to duplicate the spec files into a 3.0 and 3.1 Folder and use them according to the given OpenAPI version.
The positive parts are that static code analysis or the IDE knows which type of Object is used and the user don't have to handle multiple types. For example the `type` as string in OpenAPi 3.0 and `type` as array in OpenAPI 3.1 with null item. Also the spec could be validated and it's not necessary to add version switches for fields that are required or not.
The second Idea is to "convert" the Structure into the existing Spec Files. So a type with two items in OpenAPI would be an `oneOf` or if the type includes `null` the nullable flag would be added. But then you need to convert the items back to the new structure if you want to write a OpenAPI 3.1 file. The other part is, that you then support a converter from OpenAPI 3.0 to OpenAPI 3.1 and i don't think this is a feature to maintain in this library.
The last solution is to try to handle both versions into a single file. But that could be hard because of the breaking changes in OpenAPI 3.1. Even OpenAPI 3.1 didn't make a release without breaking changes. It could be complex to handle it here.
My preferred solution is version one because of the strict types and the clear break between Version 3.0 and 3.1
The Version and Specs for Version 3.0 are already feature complete and all changes effects only the new Spec files and couldn't break anything.
I look forward to your opinion. Maybe this should be clear before we make more changes into https://github.com/cebe/php-openapi/pull/128 ?
Hướng dẫn đóng góp
Chưa lập chỉ mục được hướng dẫn đóng góp cho kho mã nguồn này
Hướng nghiên cứu
Bắt đầu bằng cách đọc các tệp đặc tả OpenAPI 3.0 hiện có và các thay đổi trong pull request 128, sau đó so sánh chúng với các breaking changes của OpenAPI 3.1 được liệt kê và các release notes được liên kết. RFC này chỉ hoàn tất sau khi các maintainer chọn và ghi lại một phương án để biểu diễn 3.1 mà không làm hỏng phần hỗ trợ 3.0 đã hoàn thành.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Đánh giá
- Công nghệ
- openapi, php
- Lĩnh vực
- api, backend-api-design
- Loại issue
- Tính năng
- Độ khó
- 5/5
- Thời gian dự kiến
- Hơn một tuần
- Mức độ hoạt động
- Đình trệ
- Độ rõ ràng
- Cần làm rõ
- Mức phù hợp với người mới
- 25/100