MoreLogin công bố phiên bản snapshot hợp đồng máy đọc được trong info.version của mỗi tài liệu OpenAPI. Phiên bản dùng định dạng lịch YYYY-MM-DD và xác định hợp đồng tài liệu, không phải một đoạn phiên bản trong URL request.
| Thay đổi | Phân loại | Cách xử lý trong tài liệu |
|---|---|---|
| Thêm trường request hoặc response không bắt buộc, thêm thao tác hoặc giá trị enum | Bổ sung | Ghi vào changelog và cập nhật toàn bộ đặc tả đã bản địa hóa |
| Làm rõ mô tả hoặc sửa ví dụ mà không đổi hành vi lúc chạy | Sửa tài liệu | Ghi lại khi nó làm thay đổi hướng dẫn tích hợp |
| Biến trường không bắt buộc thành bắt buộc, xóa/đổi tên trường hoặc thao tác, thu hẹp giá trị được nhận, đổi ngữ nghĩa đã có | Phá vỡ | Cung cấp lộ trình di chuyển và một hợp đồng được version riêng trước khi xóa |
Đánh dấu thao tác bằng deprecated: true | Ngừng hỗ trợ | Ghi rõ phương án thay thế, ngày công bố, và ngày dự kiến xóa khi đã được phê duyệt |
Client nên bỏ qua các trường response và giá trị enum chưa biết khi logic nghiệp vụ cho phép. Điều này giảm hỏng hóc do các bản phát hành bổ sung.
Thao tác trong OpenAPI là nơi máy đọc được có tính thẩm quyền. Một thao tác đã ngừng hỗ trợ phải có:
deprecated: true- một mô tả nêu phương án thay thế hoặc nói rõ là không có
- một mục công bố trong changelog của API
- ngày dự kiến xóa chỉ sau khi chủ sở hữu sản phẩm và gateway phê duyệt
Hiện chưa bảo đảm một thời hạn ngừng hỗ trợ tối thiểu chung. Cho tới khi ngày xóa được công bố rõ ràng, client nên coi thao tác vẫn được hỗ trợ nhưng hãy lên kế hoạch chuyển đổi.
Hành vi lúc chạy vẫn có tính thẩm quyền. OpenAPI, ví dụ, các bản bản địa hóa, bản kê hành vi thao tác và changelog được kiểm tra cùng nhau trong CI để tránh lệch hợp đồng.
Việc vượt qua cổng chất lượng kho mã chứng minh rằng các tệp OpenAPI, ví dụ, liên kết, bản địa hóa và tài liệu quản trị nhất quán với nhau trong kho mã.
Kiểm tra hiển thị trang chứng minh rằng các tuyến tài liệu đại diện tải và hiển thị mà không có lỗi phía máy khách.
Chỉ kiểm thử smoke có xác thực trên API đã triển khai mới chứng minh được hành vi sản xuất khớp với hợp đồng đã công bố. Kho mã này mặc định không chạy kiểm thử đó, vì vậy ghi chú phát hành phải nêu riêng khi đã thực hiện xác minh sản xuất.