From 9ebcf5f2578992fe881d70b9eb259eb179c8718d Mon Sep 17 00:00:00 2001 From: Alexey Rusakov Date: Tue, 7 Mar 2023 17:51:30 +0100 Subject: [PATCH] OpenAPI compliance: avoid $ref siblings (#1457) This strives to fix all remaining cases where additional attributes (most often 'description' but not only) are provided next to $ref by wrapping $ref in allOf; and also drops allOf in a couple of places where $ref is the only element under it. --- .../newsfragments/1457.clarification | 1 + .../newsfragments/1457.clarification | 1 + .../newsfragments/1457.clarification | 1 + .../definitions/errors/rate_limited.yaml | 41 ++++++++++--------- .../definitions/event_batch.yaml | 4 +- .../client-server/definitions/push_rule.yaml | 3 +- data/api/client-server/notifications.yaml | 4 +- data/api/client-server/old_sync.yaml | 3 +- data/api/client-server/search.yaml | 4 +- data/api/identity/v2_associations.yaml | 3 +- data/api/identity/v2_invitation_signing.yaml | 3 +- .../event-schemas/m.device_list_update.yaml | 3 +- .../event-schemas/m.signing_key_update.yaml | 8 ++-- data/api/server-server/user_devices.yaml | 3 +- 14 files changed, 44 insertions(+), 38 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1457.clarification create mode 100644 changelogs/identity_service/newsfragments/1457.clarification create mode 100644 changelogs/server_server/newsfragments/1457.clarification diff --git a/changelogs/client_server/newsfragments/1457.clarification b/changelogs/client_server/newsfragments/1457.clarification new file mode 100644 index 00000000..0abd9b6c --- /dev/null +++ b/changelogs/client_server/newsfragments/1457.clarification @@ -0,0 +1 @@ +Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance. diff --git a/changelogs/identity_service/newsfragments/1457.clarification b/changelogs/identity_service/newsfragments/1457.clarification new file mode 100644 index 00000000..0abd9b6c --- /dev/null +++ b/changelogs/identity_service/newsfragments/1457.clarification @@ -0,0 +1 @@ +Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance. diff --git a/changelogs/server_server/newsfragments/1457.clarification b/changelogs/server_server/newsfragments/1457.clarification new file mode 100644 index 00000000..0abd9b6c --- /dev/null +++ b/changelogs/server_server/newsfragments/1457.clarification @@ -0,0 +1 @@ +Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance. diff --git a/data/api/client-server/definitions/errors/rate_limited.yaml b/data/api/client-server/definitions/errors/rate_limited.yaml index 1530458b..d5a8ebb1 100644 --- a/data/api/client-server/definitions/errors/rate_limited.yaml +++ b/data/api/client-server/definitions/errors/rate_limited.yaml @@ -11,23 +11,24 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -$ref: error.yaml -type: object -title: RateLimitError -description: The rate limit was reached for this request -properties: - errcode: - type: string - description: The M_LIMIT_EXCEEDED error code - example: M_LIMIT_EXCEEDED - error: - type: string - description: A human-readable error message. - example: Too many requests - retry_after_ms: - type: integer - description: |- - The amount of time in milliseconds the client should wait - before trying the request again. - example: 2000 -required: ["errcode"] +allOf: + - $ref: error.yaml + - type: object + title: RateLimitError + description: The rate limit was reached for this request + properties: + errcode: + type: string + description: The M_LIMIT_EXCEEDED error code + example: M_LIMIT_EXCEEDED + error: + type: string + description: A human-readable error message. + example: Too many requests + retry_after_ms: + type: integer + description: |- + The amount of time in milliseconds the client should wait + before trying the request again. + example: 2000 + required: ["errcode"] diff --git a/data/api/client-server/definitions/event_batch.yaml b/data/api/client-server/definitions/event_batch.yaml index e326184c..cc2453ed 100644 --- a/data/api/client-server/definitions/event_batch.yaml +++ b/data/api/client-server/definitions/event_batch.yaml @@ -16,9 +16,7 @@ properties: events: description: List of events. items: - allOf: - - $ref: ../../../event-schemas/schema/core-event-schema/event.yaml - type: object + $ref: ../../../event-schemas/schema/core-event-schema/event.yaml type: array type: object title: EventBatch diff --git a/data/api/client-server/definitions/push_rule.yaml b/data/api/client-server/definitions/push_rule.yaml index 06efad74..19ec89d5 100644 --- a/data/api/client-server/definitions/push_rule.yaml +++ b/data/api/client-server/definitions/push_rule.yaml @@ -38,8 +38,7 @@ properties: conditions: type: array items: - allOf: - - $ref: push_condition.yaml + $ref: push_condition.yaml description: |- The conditions that must hold true for an event in order for a rule to be applied to an event. A rule with no conditions always matches. Only diff --git a/data/api/client-server/notifications.yaml b/data/api/client-server/notifications.yaml index 809b2c0d..8f8b62b4 100644 --- a/data/api/client-server/notifications.yaml +++ b/data/api/client-server/notifications.yaml @@ -109,10 +109,10 @@ paths: - object - string event: - type: object title: Event description: The Event object for the event that triggered the notification. - "$ref": "definitions/client_event_without_room_id.yaml" + allOf: + - "$ref": "definitions/client_event_without_room_id.yaml" profile_tag: type: string description: The profile tag of the rule that matched this event. diff --git a/data/api/client-server/old_sync.yaml b/data/api/client-server/old_sync.yaml index 8813d10f..329289d8 100644 --- a/data/api/client-server/old_sync.yaml +++ b/data/api/client-server/old_sync.yaml @@ -221,7 +221,8 @@ paths: type: object title: "InviteEvent" description: "The invite event if `membership` is `invite`" - $ref: "definitions/client_event.yaml" + allOf: + - $ref: "definitions/client_event.yaml" messages: type: object title: PaginationChunk diff --git a/data/api/client-server/search.yaml b/data/api/client-server/search.yaml index 5454f0a1..2d45fe2a 100644 --- a/data/api/client-server/search.yaml +++ b/data/api/client-server/search.yaml @@ -204,7 +204,8 @@ paths: type: object title: Event description: The event that matched. - "$ref": "definitions/client_event.yaml" + allOf: + - "$ref": "definitions/client_event.yaml" context: type: object title: Event Context @@ -270,7 +271,6 @@ paths: type: array title: Room State items: - type: object "$ref": "definitions/client_event.yaml" groups: type: object diff --git a/data/api/identity/v2_associations.yaml b/data/api/identity/v2_associations.yaml index ae72b77c..4a83a34f 100644 --- a/data/api/identity/v2_associations.yaml +++ b/data/api/identity/v2_associations.yaml @@ -191,7 +191,8 @@ paths: The signatures of the verifying identity servers which show that the association should be trusted, if you trust the verifying identity services. - $ref: "../../schemas/server-signatures.yaml" + allOf: + - $ref: "../../schemas/server-signatures.yaml" required: - address - medium diff --git a/data/api/identity/v2_invitation_signing.yaml b/data/api/identity/v2_invitation_signing.yaml index d81b973d..2308dc7b 100644 --- a/data/api/identity/v2_invitation_signing.yaml +++ b/data/api/identity/v2_invitation_signing.yaml @@ -74,7 +74,8 @@ paths: signatures: type: object description: The signature of the mxid, sender, and token. - $ref: "../../schemas/server-signatures.yaml" + allOf: + - $ref: "../../schemas/server-signatures.yaml" token: type: string description: The token for the invitation. diff --git a/data/api/server-server/definitions/event-schemas/m.device_list_update.yaml b/data/api/server-server/definitions/event-schemas/m.device_list_update.yaml index 2221ad5f..81519e66 100644 --- a/data/api/server-server/definitions/event-schemas/m.device_list_update.yaml +++ b/data/api/server-server/definitions/event-schemas/m.device_list_update.yaml @@ -85,7 +85,8 @@ allOf: description: |- The updated identity keys (if any) for this device. May be absent if the device has no E2E keys defined. - $ref: ../../../client-server/definitions/device_keys.yaml + allOf: + - $ref: ../../../client-server/definitions/device_keys.yaml required: - user_id - device_id diff --git a/data/api/server-server/definitions/event-schemas/m.signing_key_update.yaml b/data/api/server-server/definitions/event-schemas/m.signing_key_update.yaml index 55d91141..aea99fe0 100644 --- a/data/api/server-server/definitions/event-schemas/m.signing_key_update.yaml +++ b/data/api/server-server/definitions/event-schemas/m.signing_key_update.yaml @@ -37,8 +37,8 @@ allOf: description: The user ID whose cross-signing keys have changed. example: "@alice:example.com" master_key: - type: object - $ref: ../../../client-server/definitions/cross_signing_key.yaml + allOf: + - $ref: ../../../client-server/definitions/cross_signing_key.yaml example: { "user_id": "@alice:example.com", "usage": ["master"], @@ -47,8 +47,8 @@ allOf: } } self_signing_key: - type: object - $ref: ../../../client-server/definitions/cross_signing_key.yaml + allOf: + - $ref: ../../../client-server/definitions/cross_signing_key.yaml example: { "user_id": "@alice:example.com", "usage": ["self_signing"], diff --git a/data/api/server-server/user_devices.yaml b/data/api/server-server/user_devices.yaml index 1c127f9b..14242867 100644 --- a/data/api/server-server/user_devices.yaml +++ b/data/api/server-server/user_devices.yaml @@ -76,7 +76,8 @@ paths: keys: type: object description: Identity keys for the device. - $ref: "../client-server/definitions/device_keys.yaml" + allOf: + - $ref: "../client-server/definitions/device_keys.yaml" device_display_name: type: string description: Optional display name for the device.