Add Swagger 2 docs for content repo. Add Swagger 2 CLI validator.

pull/977/head
Kegan Dougal 9 years ago
parent f9710a6e17
commit caa84c1dc1

@ -0,0 +1,93 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Content Repository API"
version: "1.0.0"
host: matrix.org
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: body
name: content
description: The content to be uploaded.
required: true
schema:
type: string
format: byte
responses:
200:
description: Information about the uploaded content.
schema:
type: object
required: ["content_uri"]
properties:
content_uri:
type: string
description: "The MXC URI to the uploaded content."
"/download/{serverName}/{mediaId}":
get:
summary: "Download content from the content repository."
produces: ["*/*"]
parameters:
- in: path
type: string
name: serverName
required: true
description: |
The server name from the ``mxc://`` URI (the authoritory component)
- in: path
type: string
name: mediaId
required: true
description: |
The media ID from the ``mxc://`` URI (the path component)
responses:
200:
description: "The content downloaded."
schema:
type: 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
description: |
The server name from the ``mxc://`` URI (the authoritory component)
- in: path
type: string
name: mediaId
required: true
description: |
The media ID from the ``mxc://`` URI (the path component)
- in: query
type: integer
name: width
description: The desired width of the thumbnail.
- in: query
type: integer
name: height
description: The desired height of the thumbnail.
- in: query
type: string
enum: ["crop", "scale"]
name: method
description: The desired resizing method.
responses:
200:
description: "A thumbnail of the requested content."
schema:
type: file

@ -0,0 +1,34 @@
"use strict";
var nopt = require("nopt");
var parser = require("swagger-parser");
var path = require("path");
var opts = nopt({
"help": Boolean,
"schema": path
}, {
"h": "--help",
"s": "--schema"
});
if (opts.help) {
console.log(
"Use swagger-parser to validate against Swagger 2.0\n"+
"Usage:\n"+
" node validator.js -s <schema_file>"
);
process.exit(0);
}
if (!opts.schema) {
console.error("No [s]chema specified.");
process.exit(1);
}
parser.parse(opts.schema, function(err, api, metadata) {
if (!err) {
console.log("%s is valid.", opts.schema);
return;
}
console.log(metadata);
console.error(err);
});
Loading…
Cancel
Save