mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-04-18 00:54:10 +02:00
862f5a3a53
Use 'x-example' to add examples to parameters which are not in 'body' (swagger doesn't define that currently). Add profile API examples. Add necessary glue and templates to make it all work.
146 lines
4.1 KiB
YAML
146 lines
4.1 KiB
YAML
swagger: '2.0'
|
|
info:
|
|
title: "Matrix Client-Server v1 Profile API"
|
|
version: "1.0.0"
|
|
host: localhost:8008
|
|
schemes:
|
|
- https
|
|
- http
|
|
basePath: /_matrix/client/api/v1
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
securityDefinitions:
|
|
accessToken:
|
|
type: apiKey
|
|
description: The user_id or application service access_token
|
|
name: access_token
|
|
in: query
|
|
paths:
|
|
"/profile/{userId}/displayname":
|
|
put:
|
|
summary: Set the user's display name.
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: path
|
|
type: string
|
|
name: userId
|
|
description: The user whose display name to set.
|
|
required: true
|
|
x-example: "@alice:example.com"
|
|
- in: body
|
|
name: displayName
|
|
description: The display name info.
|
|
required: true
|
|
schema:
|
|
type: object
|
|
example: |-
|
|
{
|
|
"displayname": "Alice Margatroid"
|
|
}
|
|
properties:
|
|
displayname:
|
|
type: string
|
|
description: The new display name for this user.
|
|
responses:
|
|
200:
|
|
description: The display name was set.
|
|
examples:
|
|
application/json: |-
|
|
{}
|
|
schema:
|
|
type: object # empty json object
|
|
429:
|
|
description: This request was rate-limited.
|
|
schema:
|
|
"$ref": "definitions/error.yaml"
|
|
get:
|
|
summary: Get the user's display name.
|
|
parameters:
|
|
- in: path
|
|
type: string
|
|
name: userId
|
|
description: The user whose display name to get.
|
|
required: true
|
|
x-example: "@alice:example.com"
|
|
responses:
|
|
200:
|
|
description: The display name for this user.
|
|
examples:
|
|
application/json: |-
|
|
{
|
|
"displayname": "Alice Margatroid"
|
|
}
|
|
schema:
|
|
type: object
|
|
properties:
|
|
displayname:
|
|
type: string
|
|
description: The user's display name if they have set one.
|
|
404:
|
|
description: There is no display name for this user or this user does not exist.
|
|
"/profile/{userId}/avatar_url":
|
|
put:
|
|
summary: Set the user's avatar URL.
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: path
|
|
type: string
|
|
name: userId
|
|
description: The user whose avatar URL to set.
|
|
required: true
|
|
x-example: "@alice:example.com"
|
|
- in: body
|
|
name: avatar_url
|
|
description: The avatar url info.
|
|
required: true
|
|
schema:
|
|
type: object
|
|
example: |-
|
|
{
|
|
"avatar_url": "mxc:/matrix.org/wefh34uihSDRGhw34"
|
|
}
|
|
properties:
|
|
avatar_url:
|
|
type: string
|
|
description: The new avatar URL for this user.
|
|
responses:
|
|
200:
|
|
description: The avatar URL was set.
|
|
examples:
|
|
application/json: |-
|
|
{}
|
|
schema:
|
|
type: object # empty json object
|
|
429:
|
|
description: This request was rate-limited.
|
|
schema:
|
|
"$ref": "definitions/error.yaml"
|
|
get:
|
|
summary: Get the user's avatar URL.
|
|
parameters:
|
|
- in: path
|
|
type: string
|
|
name: userId
|
|
description: The user whose avatar URL to get.
|
|
required: true
|
|
x-example: "@alice:example.com"
|
|
responses:
|
|
200:
|
|
description: The avatar URL for this user.
|
|
examples:
|
|
application/json: |-
|
|
{
|
|
"avatar_url": "mxc://matrix.org/SDGdghriugerRg"
|
|
}
|
|
schema:
|
|
type: object
|
|
properties:
|
|
avatar_url:
|
|
type: string
|
|
description: The user's avatar URL if they have set one.
|
|
404:
|
|
description: There is no avatar URL for this user or this user does not exist. |