wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Upgrade Swagger data to OpenAPI 3.1 (#1310)

Browse source 
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
This commit is contained in:
Kévin Commaille 2023-06-07 14:16:29 +02:00 • committed by GitHub
parent c64a616d54
commit 45b6aaf07a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
118 changed files with 15064 additions and 12727 deletions
Download patch file Download diff file Expand all files Collapse all files

224
data/api/client-server/message_pagination.yaml
View file

@ -11,21 +11,10 @@
# 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.
swagger: "2.0"
openapi: 3.1.0
info:
title: "Matrix Client-Server Rooms API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Rooms API
version: 1.0.0
paths:
"/rooms/{roomId}/messages":
get:
@ -41,16 +30,16 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room to get events from.
required: true
x-example: "!636q39766251:example.com"
example: "!636q39766251:example.com"
schema:
type: string
- in: query
type: string
name: from
x-changedInMatrixVersion:
1.3: |
"1.3": |
Previously, this field was required and paginating from the first or
last visible event in the room history wasn't supported.
description: |-
@ -66,18 +55,19 @@ paths:
from the first or last (per the value of the `dir` parameter) visible
event in the room history for the requesting user.
required: false
x-example: "s345_678_333"
example: s345_678_333
schema:
type: string
- in: query
type: string
name: to
description: |-
The token to stop returning events at. This token can be obtained from
a `prev_batch` or `next_batch` token returned by the `/sync` endpoint,
or from an `end` token returned by a previous request to this endpoint.
required: false
schema:
type: string
- in: query
type: string
enum: ["b", "f"]
name: dir
description: |-
The direction to return events from. If this is set to `f`, events
@ -85,92 +75,114 @@ paths:
is set to `b`, events will be returned in *reverse* chronological
order, again starting at `from`.
required: true
x-example: "b"
- in: query
type: integer
name: limit
description: |-
The maximum number of events to return. Default: 10.
x-example: "3"
- in: query
type: string
name: filter
description: |-
A JSON RoomEventFilter to filter returned events with.
x-example: |-
{"contains_url":true}
responses:
200:
description: A list of messages with a new token to request more.
example: b
schema:
type: object
description: A list of messages with a new token to request more.
properties:
start:
type: string
description: |-
A token corresponding to the start of `chunk`. This will be the same as
the value given in `from`.
end:
type: string
description: |-
A token corresponding to the end of `chunk`. This token can be passed
back to this endpoint to request further events.
If no further events are available (either because we have
reached the start of the timeline, or because the user does
not have permission to see any more events), this property
is omitted from the response.
chunk:
type: array
description: |-
A list of room events. The order depends on the `dir` parameter.
For `dir=b` events will be in reverse-chronological order,
for `dir=f` in chronological order. (The exact definition of `chronological`
is dependent on the server implementation.)
Note that an empty `chunk` does not *necessarily* imply that no more events
are available. Clients should continue to paginate until no `end` property
is returned.
items:
"$ref": "definitions/client_event.yaml"
state:
type: array
description: |-
A list of state events relevant to showing the `chunk`. For example, if
`lazy_load_members` is enabled in the filter then this may contain
the membership events for the senders of events in the `chunk`.
Unless `include_redundant_members` is `true`, the server
may remove membership events which would have already been
sent to the client in prior calls to this endpoint, assuming
the membership of those members has not changed.
items:
$ref: "definitions/client_event.yaml"
required: [start, chunk]
examples:
type: string
enum:
- b
- f
- in: query
name: limit
description: "The maximum number of events to return. Default: 10."
example: "3"
schema:
type: integer
- in: query
name: filter
description: A JSON RoomEventFilter to filter returned events with.
example: '{"contains_url":true}'
schema:
type: string
responses:
"200":
description: A list of messages with a new token to request more.
content:
application/json:
{
"start": "t47429-4392820_219380_26003_2265",
"end": "t47409-4357353_219380_26003_2265",
"chunk":
[
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml",
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.name.yaml",
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.message$m.video.yaml",
},
],
}
403:
description: >
schema:
type: object
description: A list of messages with a new token to request more.
properties:
start:
type: string
description: |-
A token corresponding to the start of `chunk`. This will be the same as
the value given in `from`.
end:
type: string
description: |-
A token corresponding to the end of `chunk`. This token can be passed
back to this endpoint to request further events.
If no further events are available (either because we have
reached the start of the timeline, or because the user does
not have permission to see any more events), this property
is omitted from the response.
chunk:
type: array
description: |-
A list of room events. The order depends on the `dir` parameter.
For `dir=b` events will be in reverse-chronological order,
for `dir=f` in chronological order. (The exact definition of `chronological`
is dependent on the server implementation.)
Note that an empty `chunk` does not *necessarily* imply that no more events
are available. Clients should continue to paginate until no `end` property
is returned.
items:
$ref: definitions/client_event.yaml
state:
type: array
description: |-
A list of state events relevant to showing the `chunk`. For example, if
`lazy_load_members` is enabled in the filter then this may contain
the membership events for the senders of events in the `chunk`.
Unless `include_redundant_members` is `true`, the server
may remove membership events which would have already been
sent to the client in prior calls to this endpoint, assuming
the membership of those members has not changed.
items:
$ref: definitions/client_event.yaml
required:
- start
- chunk
examples:
response:
value: {
"start": "t47429-4392820_219380_26003_2265",
"end": "t47409-4357353_219380_26003_2265",
"chunk": [
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.name.yaml"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "../../event-schemas/examples/m.room.message$m.video.yaml"
}
]
}
"403":
description: |
You aren't a member of the room.
tags:
- Room participation
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml