mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-02-02 20:43:42 +01:00
87b6dd845e
Edit content-repo.yaml to include examples and headers.
Restructure content module to conform to the module template.
Adjust the HTTP API template to give 1 more char to the response
param to fit "Content-Disposition" correctly.
Edit the templating system to support displaying enums for
swagger APIs (before it was just JSON schema). Also add support
for introspecting headers from swagger. Finally, replace - with
_ when forming the {{ template_var }} else things whine.
133 lines
4 KiB
YAML
133 lines
4 KiB
YAML
swagger: '2.0'
|
|
info:
|
|
title: "Matrix Client-Server v1 Content Repository API"
|
|
version: "1.0.0"
|
|
host: localhost:8008
|
|
schemes:
|
|
- https
|
|
basePath: /_matrix/media/v1
|
|
produces:
|
|
- application/json
|
|
- "*/*"
|
|
paths:
|
|
"/upload":
|
|
post:
|
|
summary: Upload some content to the content repository.
|
|
produces: ["application/json"]
|
|
parameters:
|
|
- in: header
|
|
name: Content-Type
|
|
type: string
|
|
description: The content type of the file being uploaded
|
|
x-example: "Content-Type: audio/mpeg"
|
|
- in: body
|
|
name: "<content>"
|
|
description: The content to be uploaded.
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: "<bytes>"
|
|
format: byte
|
|
responses:
|
|
200:
|
|
description: The MXC URI for the uploaded content.
|
|
schema:
|
|
type: object
|
|
required: ["content_uri"]
|
|
properties:
|
|
content_uri:
|
|
type: string
|
|
description: "The MXC URI to the uploaded content."
|
|
examples:
|
|
"application/json": |-
|
|
{
|
|
"content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw"
|
|
}
|
|
"/download/{serverName}/{mediaId}":
|
|
get:
|
|
summary: "Download content from the content repository."
|
|
produces: ["*/*"]
|
|
parameters:
|
|
- in: path
|
|
type: string
|
|
name: serverName
|
|
x-example: matrix.org
|
|
required: true
|
|
description: |
|
|
The server name from the ``mxc://`` URI (the authoritory component)
|
|
- in: path
|
|
type: string
|
|
name: mediaId
|
|
x-example: ascERGshawAWawugaAcauga
|
|
required: true
|
|
description: |
|
|
The media ID from the ``mxc://`` URI (the path component)
|
|
responses:
|
|
200:
|
|
description: "The content that was previously uploaded."
|
|
headers:
|
|
Content-Type:
|
|
description: "The content type of the file that was previously uploaded."
|
|
x-example: "audio/mpeg"
|
|
type: "string"
|
|
Content-Disposition:
|
|
description: "The name of the file that was previously uploaded, if set."
|
|
x-example: "attachment;filename=03-cool.mp3"
|
|
type: "string"
|
|
schema:
|
|
type: file
|
|
name: "<file>"
|
|
"/thumbnail/{serverName}/{mediaId}":
|
|
get:
|
|
summary: "Download a thumbnail of the content from the content repository."
|
|
produces: ["image/jpeg", "image/png"]
|
|
parameters:
|
|
- in: path
|
|
type: string
|
|
name: serverName
|
|
required: true
|
|
x-example: matrix.org
|
|
description: |
|
|
The server name from the ``mxc://`` URI (the authoritory component)
|
|
- in: path
|
|
type: string
|
|
name: mediaId
|
|
x-example: ascERGshawAWawugaAcauga
|
|
required: true
|
|
description: |
|
|
The media ID from the ``mxc://`` URI (the path component)
|
|
- in: query
|
|
type: integer
|
|
x-example: 64
|
|
name: width
|
|
description: |-
|
|
The *desired* width of the thumbnail. The actual thumbnail may not
|
|
match the size specified.
|
|
- in: query
|
|
type: integer
|
|
x-example: 64
|
|
name: height
|
|
description: |-
|
|
The *desired* height of the thumbnail. The actual thumbnail may not
|
|
match the size specified.
|
|
- in: query
|
|
type: string
|
|
enum: ["crop", "scale"]
|
|
name: method
|
|
x-example: "scale"
|
|
description: The desired resizing method.
|
|
responses:
|
|
200:
|
|
description: "A thumbnail of the requested content."
|
|
headers:
|
|
Content-Type:
|
|
description: "The content type of the thumbnail."
|
|
x-example: "image/jpeg"
|
|
type: "string"
|
|
enum: ["image/jpeg", "image/png"]
|
|
schema:
|
|
type: file
|
|
name: "<file>"
|
|
|
|
|