mirror of
https://github.com/matrix-org/matrix-spec
synced 2025-12-24 18:08:37 +01:00
820704a16a
According the the openapi spec, examples for responses and schemas should be raw objects rather than being json strings. (It's unclear what non-json examples should look like...). The swagger UI used to support json strings, but no longer does. In short, let's turn the json strings into their raw formats.
210 lines
6.8 KiB
YAML
210 lines
6.8 KiB
YAML
# Copyright 2016 OpenMarket Ltd
|
|
#
|
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
# you may not use this file except in compliance with the License.
|
|
# You may obtain a copy of the License at
|
|
#
|
|
# http://www.apache.org/licenses/LICENSE-2.0
|
|
#
|
|
# Unless required by applicable law or agreed to in writing, software
|
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
# 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'
|
|
info:
|
|
title: "Matrix Client-Server Profile API"
|
|
version: "1.0.0"
|
|
host: localhost:8008
|
|
schemes:
|
|
- https
|
|
- http
|
|
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
securityDefinitions:
|
|
$ref: definitions/security.yaml
|
|
paths:
|
|
"/profile/{userId}/displayname":
|
|
put:
|
|
summary: Set the user's display name.
|
|
description: |-
|
|
This API sets the given user's display name. You must have permission to
|
|
set this user's display name, e.g. you need to have their ``access_token``.
|
|
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"
|
|
tags:
|
|
- User data
|
|
get:
|
|
summary: Get the user's display name.
|
|
description: |-
|
|
Get the user's display name. This API may be used to fetch the user's
|
|
own displayname or to query the name of other users; either locally or
|
|
on remote homeservers.
|
|
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, otherwise not present.
|
|
404:
|
|
description: There is no display name for this user or this user does not exist.
|
|
tags:
|
|
- User data
|
|
"/profile/{userId}/avatar_url":
|
|
put:
|
|
summary: Set the user's avatar URL.
|
|
description: |-
|
|
This API sets the given user's avatar URL. You must have permission to
|
|
set this user's avatar URL, e.g. you need to have their ``access_token``.
|
|
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"
|
|
tags:
|
|
- User data
|
|
get:
|
|
summary: Get the user's avatar URL.
|
|
description: |-
|
|
Get the user's avatar URL. This API may be used to fetch the user's
|
|
own avatar URL or to query the URL of other users; either locally or
|
|
on remote homeservers.
|
|
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, otherwise not present.
|
|
404:
|
|
description: There is no avatar URL for this user or this user does not exist.
|
|
tags:
|
|
- User data
|
|
"/profile/{userId}":
|
|
get:
|
|
summary: Get this user's profile information.
|
|
description: |-
|
|
Get the combined profile information for this user. This API may be used
|
|
to fetch the user's own profile information or other users; either
|
|
locally or on remote homeservers. This API may return keys which are not
|
|
limited to ``displayname`` or ``avatar_url``.
|
|
parameters:
|
|
- in: path
|
|
type: string
|
|
name: userId
|
|
description: The user whose profile information 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",
|
|
"displayname": "Alice Margatroid"
|
|
}
|
|
schema:
|
|
type: object
|
|
properties:
|
|
avatar_url:
|
|
type: string
|
|
description: The user's avatar URL if they have set one, otherwise not present.
|
|
displayname:
|
|
type: string
|
|
description: The user's display name if they have set one, otherwise not present.
|
|
404:
|
|
description: There is no profile information for this user or this user does not exist.
|
|
tags:
|
|
- User data
|