From 667c39f2595818316c158a0d136f636ae16f9143 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Tue, 9 May 2023 15:39:37 +0200 Subject: [PATCH 1/7] Create Swagger 2.0 to OpenAPI 3.1 conversion scripts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- .../openapi-convert/convert-definitions.mjs | 83 ++ scripts/openapi-convert/index.mjs | 40 + scripts/openapi-convert/object-fixes.mjs | 49 + scripts/openapi-convert/package-lock.json | 1292 +++++++++++++++++ scripts/openapi-convert/package.json | 17 + scripts/openapi-convert/string-fixes.mjs | 165 +++ 6 files changed, 1646 insertions(+) create mode 100644 scripts/openapi-convert/convert-definitions.mjs create mode 100644 scripts/openapi-convert/index.mjs create mode 100644 scripts/openapi-convert/object-fixes.mjs create mode 100644 scripts/openapi-convert/package-lock.json create mode 100644 scripts/openapi-convert/package.json create mode 100644 scripts/openapi-convert/string-fixes.mjs diff --git a/scripts/openapi-convert/convert-definitions.mjs b/scripts/openapi-convert/convert-definitions.mjs new file mode 100644 index 000000000..6e3169765 --- /dev/null +++ b/scripts/openapi-convert/convert-definitions.mjs @@ -0,0 +1,83 @@ +"use strict"; +import fs from 'node:fs/promises'; +import converter from 'swagger2openapi'; +import path_utils from 'node:path'; +import yaml from 'yaml'; + +import { applyObjectFixes } from './object-fixes.mjs'; + +async function getStartComment(path) { + const file = await fs.open(path); + + let start_comment = ""; + for await (const line of file.readLines()) { + if (line.startsWith('#')) { + start_comment += line + '\n'; + } else { + break; + } + }; + + await file.close(); + + return start_comment +} + +async function convertDefinitionsFile(path) { + let relative_separator = path.lastIndexOf('/data/api'); + let short_path = path.slice(relative_separator + 1); + console.log("%s", short_path); + + // Save the comments at the start of the file to not lose them. + let start_comment = await getStartComment(path); + + // Convert. + const options = await converter.convertFile(path, { + // Patch fixable errors. + patch: true, + // Keep $ref siblings. + refSiblings: 'preserve', + // Don't deduplicate requestBodies. + resolveInternal: true, + // Write OpenAPI version 3.1.0, even if it's not completely true, it'll + // be fixed later. + targetVersion: '3.1.0', + }); + + // Apply fixes on object. + const obj = applyObjectFixes(options.openapi); + + // Serialize. + const doc = new yaml.Document(obj); + const content = yaml.stringify(doc, { + // Use "literal" blocks, like the input. + blockQuote: "literal" + }); + + // Save to file. + await fs.writeFile(path, start_comment + content); +} + +export async function convertDefinitionsDir(path) { + console.log("Converting files in %s", path); + + const files = await fs.readdir(path); + + for (const file of files) { + if (file.endsWith(".yaml")) { + await convertDefinitionsFile(path_utils.join(path, file)); + } + } +} + +// Convert Swagger 2.0 definitions to OpenAPI 3.0.0. +export async function convertDefinitions(path) { + // We don't want to try to convert schemas in subdirectories, so we need to + // call this separately for every directory inside `data/api`. + let api_dir = path_utils.join(path, "api"); + const files = await fs.readdir(api_dir); + + for (const file of files) { + await convertDefinitionsDir(path_utils.join(api_dir, file)); + } +} \ No newline at end of file diff --git a/scripts/openapi-convert/index.mjs b/scripts/openapi-convert/index.mjs new file mode 100644 index 000000000..e7fea1b5a --- /dev/null +++ b/scripts/openapi-convert/index.mjs @@ -0,0 +1,40 @@ +"use strict"; +import nopt from 'nopt'; + +import { convertDefinitions } from './convert-definitions.mjs'; +import { applyStringFixes } from './string-fixes.mjs'; + +const opts = nopt({ + "help": Boolean, + "data": String +}, { + "h": "--help", + "d": "--data" +}); + +console.log("params: {}", opts); +if (opts.help) { + console.log( + "Convert the definitions from Swagger 2.0 to OpenAPI 3.0\n" + + "Usage:\n" + + " node index.mjs -d " + ); + process.exit(0); +} +if (!opts.data) { + console.error("No [d]ata dir specified."); + process.exit(1); +} + +console.log("Converting Swagger 2.0 definitions to OpenAPI 3.0 in %s...", opts.data); +try { + await convertDefinitions(opts.data); + + console.log("Applying string fixes..."); + await applyStringFixes(opts.data); + + console.log(" ✅ Success"); +} catch (err) { + console.error(' ❌ {}', err); + process.exit(1); +} diff --git a/scripts/openapi-convert/object-fixes.mjs b/scripts/openapi-convert/object-fixes.mjs new file mode 100644 index 000000000..e484f2895 --- /dev/null +++ b/scripts/openapi-convert/object-fixes.mjs @@ -0,0 +1,49 @@ +"use strict"; +import { URL } from 'node:url'; + +// Refactor `servers` field to be able to access `basePath` easily. +function refactorServers(obj) { + if (!obj.servers) { + return; + } + + let server = { + url: "", + variables: { + protocol: {}, + hostname: { + default: "" + }, + basePath: { + default: "" + } + } + } + + const url = new URL(obj.servers[0].url); + + if (obj.servers.length > 1) { + // In our case several URLs always mean both http and https for the same + // host. + obj.servers.pop() + } + + server.url = "{protocol}://{hostname}{basePath}" + server.variables.protocol = { + enum: ["http", "https"], + default: "https", + } + server.variables.hostname.default = url.host + server.variables.basePath.default = url.pathname + + obj.servers[0] = server; + + return obj; +} + +// Fixes to apply to a converted schema object. +export function applyObjectFixes(obj) { + obj = refactorServers(obj); + + return obj; +} \ No newline at end of file diff --git a/scripts/openapi-convert/package-lock.json b/scripts/openapi-convert/package-lock.json new file mode 100644 index 000000000..408d7fecf --- /dev/null +++ b/scripts/openapi-convert/package-lock.json @@ -0,0 +1,1292 @@ +{ + "name": "openapi-convert", + "version": "1.0.0", + "lockfileVersion": 2, + "requires": true, + "packages": { + "": { + "name": "openapi-convert", + "version": "1.0.0", + "license": "ISC", + "dependencies": { + "nopt": "^3.0.2", + "replace": "^1.2.2", + "swagger2openapi": "^7.0.8", + "yaml": "^2.1.3" + } + }, + "node_modules/@exodus/schemasafe": { + "version": "1.0.0-rc.9", + "resolved": "https://registry.npmjs.org/@exodus/schemasafe/-/schemasafe-1.0.0-rc.9.tgz", + "integrity": "sha512-dGGHpb61hLwifAu7sotuHFDBw6GTdpG8aKC0fsK17EuTzMRvUrH7lEAr6LTJ+sx3AZYed9yZ77rltVDHyg2hRg==" + }, + "node_modules/abbrev": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/abbrev/-/abbrev-1.1.1.tgz", + "integrity": "sha512-nne9/IiQ/hzIhY6pdDnbBtz7DjPTKrY00P/zvPSm5pOFkl6xuGrGnXn/VtTNNfNtAfZ9/1RtehkszU9qcTii0Q==" + }, + "node_modules/ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "engines": { + "node": ">=8" + } + }, + "node_modules/ansi-styles": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", + "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", + "dependencies": { + "color-convert": "^2.0.1" + }, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/chalk/ansi-styles?sponsor=1" + } + }, + "node_modules/balanced-match": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz", + "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==" + }, + "node_modules/brace-expansion": { + "version": "1.1.11", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz", + "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==", + "dependencies": { + "balanced-match": "^1.0.0", + "concat-map": "0.0.1" + } + }, + "node_modules/call-me-maybe": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/call-me-maybe/-/call-me-maybe-1.0.2.tgz", + "integrity": "sha512-HpX65o1Hnr9HH25ojC1YGs7HCQLq0GCOibSaWER0eNpgJ/Z1MZv2mTc7+xh6WOPxbRVcmgbv4hGU+uSQ/2xFZQ==" + }, + "node_modules/camelcase": { + "version": "5.3.1", + "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-5.3.1.tgz", + "integrity": "sha512-L28STB170nwWS63UjtlEOE3dldQApaJXZkOI1uMFfzf3rRuPegHaHesyee+YxQ+W6SvRDQV6UrdOdRiR153wJg==", + "engines": { + "node": ">=6" + } + }, + "node_modules/chalk": { + "version": "2.4.2", + "resolved": "https://registry.npmjs.org/chalk/-/chalk-2.4.2.tgz", + "integrity": "sha512-Mti+f9lpJNcwF4tWV8/OrTTtF1gZi+f8FqlyAdouralcFWFQWF2+NgCHShjkCb+IFBLq9buZwE1xckQU4peSuQ==", + "dependencies": { + "ansi-styles": "^3.2.1", + "escape-string-regexp": "^1.0.5", + "supports-color": "^5.3.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/chalk/node_modules/ansi-styles": { + "version": "3.2.1", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-3.2.1.tgz", + "integrity": "sha512-VT0ZI6kZRdTh8YyJw3SMbYm/u+NqfsAxEpWO0Pf9sq8/e94WxxOpPKx9FR1FlyCtOVDNOQ+8ntlqFxiRc+r5qA==", + "dependencies": { + "color-convert": "^1.9.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/chalk/node_modules/color-convert": { + "version": "1.9.3", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-1.9.3.tgz", + "integrity": "sha512-QfAUtd+vFdAtFQcC8CCyYt1fYWxSqAiK2cSD6zDB8N3cpsEBAvRxp9zOGg6G/SHHJYAT88/az/IuDGALsNVbGg==", + "dependencies": { + "color-name": "1.1.3" + } + }, + "node_modules/chalk/node_modules/color-name": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.3.tgz", + "integrity": "sha512-72fSenhMw2HZMTVHeCA9KCmpEIbzWiQsjN+BHcBbS9vr1mtt+vJjPdksIBNUmKAW8TFUDPJK5SUU3QhE9NEXDw==" + }, + "node_modules/cliui": { + "version": "8.0.1", + "resolved": "https://registry.npmjs.org/cliui/-/cliui-8.0.1.tgz", + "integrity": "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==", + "dependencies": { + "string-width": "^4.2.0", + "strip-ansi": "^6.0.1", + "wrap-ansi": "^7.0.0" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/color-convert": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", + "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", + "dependencies": { + "color-name": "~1.1.4" + }, + "engines": { + "node": ">=7.0.0" + } + }, + "node_modules/color-name": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", + "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==" + }, + "node_modules/concat-map": { + "version": "0.0.1", + "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz", + "integrity": "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==" + }, + "node_modules/decamelize": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/decamelize/-/decamelize-1.2.0.tgz", + "integrity": "sha512-z2S+W9X73hAUUki+N+9Za2lBlun89zigOyGrsax+KUQ6wKW4ZoWpEYBkGhQjwAjjDCkWxhY0VKEhk8wzY7F5cA==", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/emoji-regex": { + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz", + "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==" + }, + "node_modules/es6-promise": { + "version": "3.3.1", + "resolved": "https://registry.npmjs.org/es6-promise/-/es6-promise-3.3.1.tgz", + "integrity": "sha512-SOp9Phqvqn7jtEUxPWdWfWoLmyt2VaJ6MpvP9Comy1MceMXqE6bxvaTu4iaxpYYPzhny28Lc+M87/c2cPK6lDg==" + }, + "node_modules/escalade": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.1.1.tgz", + "integrity": "sha512-k0er2gUkLf8O0zKJiAhmkTnJlTvINGv7ygDNPbeIsX/TJjGJZHuh9B2UxbsaEkmlEo9MfhrSzmhIlhRlI2GXnw==", + "engines": { + "node": ">=6" + } + }, + "node_modules/escape-string-regexp": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-1.0.5.tgz", + "integrity": "sha512-vbRorB5FUQWvla16U8R/qgaFIya2qGzwDrNmCZuYKrbdSUMG6I1ZCGQRefkRVhuOkIGVne7BQ35DSfo1qvJqFg==", + "engines": { + "node": ">=0.8.0" + } + }, + "node_modules/fast-safe-stringify": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/fast-safe-stringify/-/fast-safe-stringify-2.1.1.tgz", + "integrity": "sha512-W+KJc2dmILlPplD/H4K9l9LcAHAfPtP6BY84uVLXQ6Evcz9Lcg33Y2z1IVblT6xdY54PXYVHEv+0Wpq8Io6zkA==" + }, + "node_modules/find-up": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/find-up/-/find-up-4.1.0.tgz", + "integrity": "sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw==", + "dependencies": { + "locate-path": "^5.0.0", + "path-exists": "^4.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/get-caller-file": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz", + "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==", + "engines": { + "node": "6.* || 8.* || >= 10.*" + } + }, + "node_modules/has-flag": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-3.0.0.tgz", + "integrity": "sha512-sKJf1+ceQBr4SMkvQnBDNDtf4TXpVhVGateu0t918bl30FnbE2m4vNLX+VWe/dpjlb+HugGYzW7uQXH98HPEYw==", + "engines": { + "node": ">=4" + } + }, + "node_modules/http2-client": { + "version": "1.3.5", + "resolved": "https://registry.npmjs.org/http2-client/-/http2-client-1.3.5.tgz", + "integrity": "sha512-EC2utToWl4RKfs5zd36Mxq7nzHHBuomZboI0yYL6Y0RmBgT7Sgkq4rQ0ezFTYoIsSs7Tm9SJe+o2FcAg6GBhGA==" + }, + "node_modules/is-fullwidth-code-point": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", + "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==", + "engines": { + "node": ">=8" + } + }, + "node_modules/locate-path": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-5.0.0.tgz", + "integrity": "sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g==", + "dependencies": { + "p-locate": "^4.1.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/minimatch": { + "version": "3.0.5", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.0.5.tgz", + "integrity": "sha512-tUpxzX0VAzJHjLu0xUfFv1gwVp9ba3IOuRAVH2EGuRW8a5emA2FlACLqiT/lDVtS1W+TGNwqz3sWaNyLgDJWuw==", + "dependencies": { + "brace-expansion": "^1.1.7" + }, + "engines": { + "node": "*" + } + }, + "node_modules/node-fetch": { + "version": "2.6.7", + "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.6.7.tgz", + "integrity": "sha512-ZjMPFEfVx5j+y2yF35Kzx5sF7kDzxuDj6ziH4FFbOp87zKDZNx8yExJIb05OGF4Nlt9IHFIMBkRl41VdvcNdbQ==", + "dependencies": { + "whatwg-url": "^5.0.0" + }, + "engines": { + "node": "4.x || >=6.0.0" + }, + "peerDependencies": { + "encoding": "^0.1.0" + }, + "peerDependenciesMeta": { + "encoding": { + "optional": true + } + } + }, + "node_modules/node-fetch-h2": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/node-fetch-h2/-/node-fetch-h2-2.3.0.tgz", + "integrity": "sha512-ofRW94Ab0T4AOh5Fk8t0h8OBWrmjb0SSB20xh1H8YnPV9EJ+f5AMoYSUQ2zgJ4Iq2HAK0I2l5/Nequ8YzFS3Hg==", + "dependencies": { + "http2-client": "^1.2.5" + }, + "engines": { + "node": "4.x || >=6.0.0" + } + }, + "node_modules/node-readfiles": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/node-readfiles/-/node-readfiles-0.2.0.tgz", + "integrity": "sha512-SU00ZarexNlE4Rjdm83vglt5Y9yiQ+XI1XpflWlb7q7UTN1JUItm69xMeiQCTxtTfnzt+83T8Cx+vI2ED++VDA==", + "dependencies": { + "es6-promise": "^3.2.1" + } + }, + "node_modules/nopt": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/nopt/-/nopt-3.0.2.tgz", + "integrity": "sha512-WoB9oKq8r03hlIeU/PvXzsE2XaI97VQMSbw+8YoybgGI/Mow+qeFi7TDpVLCFEBaAhnp8uj5f7kQsuTgTCjRFA==", + "dependencies": { + "abbrev": "1" + }, + "bin": { + "nopt": "bin/nopt.js" + } + }, + "node_modules/oas-kit-common": { + "version": "1.0.8", + "resolved": "https://registry.npmjs.org/oas-kit-common/-/oas-kit-common-1.0.8.tgz", + "integrity": "sha512-pJTS2+T0oGIwgjGpw7sIRU8RQMcUoKCDWFLdBqKB2BNmGpbBMH2sdqAaOXUg8OzonZHU0L7vfJu1mJFEiYDWOQ==", + "dependencies": { + "fast-safe-stringify": "^2.0.7" + } + }, + "node_modules/oas-linter": { + "version": "3.2.2", + "resolved": "https://registry.npmjs.org/oas-linter/-/oas-linter-3.2.2.tgz", + "integrity": "sha512-KEGjPDVoU5K6swgo9hJVA/qYGlwfbFx+Kg2QB/kd7rzV5N8N5Mg6PlsoCMohVnQmo+pzJap/F610qTodKzecGQ==", + "dependencies": { + "@exodus/schemasafe": "^1.0.0-rc.2", + "should": "^13.2.1", + "yaml": "^1.10.0" + }, + "funding": { + "url": "https://github.com/Mermade/oas-kit?sponsor=1" + } + }, + "node_modules/oas-linter/node_modules/yaml": { + "version": "1.10.2", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.2.tgz", + "integrity": "sha512-r3vXyErRCYJ7wg28yvBY5VSoAF8ZvlcW9/BwUzEtUsjvX/DKs24dIkuwjtuprwJJHsbyUbLApepYTR1BN4uHrg==", + "engines": { + "node": ">= 6" + } + }, + "node_modules/oas-resolver": { + "version": "2.5.6", + "resolved": "https://registry.npmjs.org/oas-resolver/-/oas-resolver-2.5.6.tgz", + "integrity": "sha512-Yx5PWQNZomfEhPPOphFbZKi9W93CocQj18NlD2Pa4GWZzdZpSJvYwoiuurRI7m3SpcChrnO08hkuQDL3FGsVFQ==", + "dependencies": { + "node-fetch-h2": "^2.3.0", + "oas-kit-common": "^1.0.8", + "reftools": "^1.1.9", + "yaml": "^1.10.0", + "yargs": "^17.0.1" + }, + "bin": { + "resolve": "resolve.js" + }, + "funding": { + "url": "https://github.com/Mermade/oas-kit?sponsor=1" + } + }, + "node_modules/oas-resolver/node_modules/yaml": { + "version": "1.10.2", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.2.tgz", + "integrity": "sha512-r3vXyErRCYJ7wg28yvBY5VSoAF8ZvlcW9/BwUzEtUsjvX/DKs24dIkuwjtuprwJJHsbyUbLApepYTR1BN4uHrg==", + "engines": { + "node": ">= 6" + } + }, + "node_modules/oas-schema-walker": { + "version": "1.1.5", + "resolved": "https://registry.npmjs.org/oas-schema-walker/-/oas-schema-walker-1.1.5.tgz", + "integrity": "sha512-2yucenq1a9YPmeNExoUa9Qwrt9RFkjqaMAA1X+U7sbb0AqBeTIdMHky9SQQ6iN94bO5NW0W4TRYXerG+BdAvAQ==", + "funding": { + "url": "https://github.com/Mermade/oas-kit?sponsor=1" + } + }, + "node_modules/oas-validator": { + "version": "5.0.8", + "resolved": "https://registry.npmjs.org/oas-validator/-/oas-validator-5.0.8.tgz", + "integrity": "sha512-cu20/HE5N5HKqVygs3dt94eYJfBi0TsZvPVXDhbXQHiEityDN+RROTleefoKRKKJ9dFAF2JBkDHgvWj0sjKGmw==", + "dependencies": { + "call-me-maybe": "^1.0.1", + "oas-kit-common": "^1.0.8", + "oas-linter": "^3.2.2", + "oas-resolver": "^2.5.6", + "oas-schema-walker": "^1.1.5", + "reftools": "^1.1.9", + "should": "^13.2.1", + "yaml": "^1.10.0" + }, + "funding": { + "url": "https://github.com/Mermade/oas-kit?sponsor=1" + } + }, + "node_modules/oas-validator/node_modules/yaml": { + "version": "1.10.2", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.2.tgz", + "integrity": "sha512-r3vXyErRCYJ7wg28yvBY5VSoAF8ZvlcW9/BwUzEtUsjvX/DKs24dIkuwjtuprwJJHsbyUbLApepYTR1BN4uHrg==", + "engines": { + "node": ">= 6" + } + }, + "node_modules/p-limit": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-2.3.0.tgz", + "integrity": "sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==", + "dependencies": { + "p-try": "^2.0.0" + }, + "engines": { + "node": ">=6" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/p-locate": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-4.1.0.tgz", + "integrity": "sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A==", + "dependencies": { + "p-limit": "^2.2.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/p-try": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/p-try/-/p-try-2.2.0.tgz", + "integrity": "sha512-R4nPAVTAU0B9D35/Gk3uJf/7XYbQcyohSKdvAxIRSNghFl4e71hVoGnBNQz9cWaXxO2I10KTC+3jMdvvoKw6dQ==", + "engines": { + "node": ">=6" + } + }, + "node_modules/path-exists": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-4.0.0.tgz", + "integrity": "sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==", + "engines": { + "node": ">=8" + } + }, + "node_modules/reftools": { + "version": "1.1.9", + "resolved": "https://registry.npmjs.org/reftools/-/reftools-1.1.9.tgz", + "integrity": "sha512-OVede/NQE13xBQ+ob5CKd5KyeJYU2YInb1bmV4nRoOfquZPkAkxuOXicSe1PvqIuZZ4kD13sPKBbR7UFDmli6w==", + "funding": { + "url": "https://github.com/Mermade/oas-kit?sponsor=1" + } + }, + "node_modules/replace": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/replace/-/replace-1.2.2.tgz", + "integrity": "sha512-C4EDifm22XZM2b2JOYe6Mhn+lBsLBAvLbK8drfUQLTfD1KYl/n3VaW/CDju0Ny4w3xTtegBpg8YNSpFJPUDSjA==", + "dependencies": { + "chalk": "2.4.2", + "minimatch": "3.0.5", + "yargs": "^15.3.1" + }, + "bin": { + "replace": "bin/replace.js", + "search": "bin/search.js" + }, + "engines": { + "node": ">= 6" + } + }, + "node_modules/replace/node_modules/cliui": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/cliui/-/cliui-6.0.0.tgz", + "integrity": "sha512-t6wbgtoCXvAzst7QgXxJYqPt0usEfbgQdftEPbLL/cvv6HPE5VgvqCuAIDR0NgU52ds6rFwqrgakNLrHEjCbrQ==", + "dependencies": { + "string-width": "^4.2.0", + "strip-ansi": "^6.0.0", + "wrap-ansi": "^6.2.0" + } + }, + "node_modules/replace/node_modules/wrap-ansi": { + "version": "6.2.0", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-6.2.0.tgz", + "integrity": "sha512-r6lPcBGxZXlIcymEu7InxDMhdW0KDxpLgoFLcguasxCaJ/SOIZwINatK9KY/tf+ZrlywOKU0UDj3ATXUBfxJXA==", + "dependencies": { + "ansi-styles": "^4.0.0", + "string-width": "^4.1.0", + "strip-ansi": "^6.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/replace/node_modules/y18n": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/y18n/-/y18n-4.0.3.tgz", + "integrity": "sha512-JKhqTOwSrqNA1NY5lSztJ1GrBiUodLMmIZuLiDaMRJ+itFd+ABVE8XBjOvIWL+rSqNDC74LCSFmlb/U4UZ4hJQ==" + }, + "node_modules/replace/node_modules/yargs": { + "version": "15.4.1", + "resolved": "https://registry.npmjs.org/yargs/-/yargs-15.4.1.tgz", + "integrity": "sha512-aePbxDmcYW++PaqBsJ+HYUFwCdv4LVvdnhBy78E57PIor8/OVvhMrADFFEDh8DHDFRv/O9i3lPhsENjO7QX0+A==", + "dependencies": { + "cliui": "^6.0.0", + "decamelize": "^1.2.0", + "find-up": "^4.1.0", + "get-caller-file": "^2.0.1", + "require-directory": "^2.1.1", + "require-main-filename": "^2.0.0", + "set-blocking": "^2.0.0", + "string-width": "^4.2.0", + "which-module": "^2.0.0", + "y18n": "^4.0.0", + "yargs-parser": "^18.1.2" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/replace/node_modules/yargs-parser": { + "version": "18.1.3", + "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-18.1.3.tgz", + "integrity": "sha512-o50j0JeToy/4K6OZcaQmW6lyXXKhq7csREXcDwk2omFPJEwUNOVtJKvmDr9EI1fAJZUyZcRF7kxGBWmRXudrCQ==", + "dependencies": { + "camelcase": "^5.0.0", + "decamelize": "^1.2.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/require-directory": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz", + "integrity": "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/require-main-filename": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/require-main-filename/-/require-main-filename-2.0.0.tgz", + "integrity": "sha512-NKN5kMDylKuldxYLSUfrbo5Tuzh4hd+2E8NPPX02mZtn1VuREQToYe/ZdlJy+J3uCpfaiGF05e7B8W0iXbQHmg==" + }, + "node_modules/set-blocking": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/set-blocking/-/set-blocking-2.0.0.tgz", + "integrity": "sha512-KiKBS8AnWGEyLzofFfmvKwpdPzqiy16LvQfK3yv/fVH7Bj13/wl3JSR1J+rfgRE9q7xUJK4qvgS8raSOeLUehw==" + }, + "node_modules/should": { + "version": "13.2.3", + "resolved": "https://registry.npmjs.org/should/-/should-13.2.3.tgz", + "integrity": "sha512-ggLesLtu2xp+ZxI+ysJTmNjh2U0TsC+rQ/pfED9bUZZ4DKefP27D+7YJVVTvKsmjLpIi9jAa7itwDGkDDmt1GQ==", + "dependencies": { + "should-equal": "^2.0.0", + "should-format": "^3.0.3", + "should-type": "^1.4.0", + "should-type-adaptors": "^1.0.1", + "should-util": "^1.0.0" + } + }, + "node_modules/should-equal": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/should-equal/-/should-equal-2.0.0.tgz", + "integrity": "sha512-ZP36TMrK9euEuWQYBig9W55WPC7uo37qzAEmbjHz4gfyuXrEUgF8cUvQVO+w+d3OMfPvSRQJ22lSm8MQJ43LTA==", + "dependencies": { + "should-type": "^1.4.0" + } + }, + "node_modules/should-format": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/should-format/-/should-format-3.0.3.tgz", + "integrity": "sha512-hZ58adtulAk0gKtua7QxevgUaXTTXxIi8t41L3zo9AHvjXO1/7sdLECuHeIN2SRtYXpNkmhoUP2pdeWgricQ+Q==", + "dependencies": { + "should-type": "^1.3.0", + "should-type-adaptors": "^1.0.1" + } + }, + "node_modules/should-type": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/should-type/-/should-type-1.4.0.tgz", + "integrity": "sha512-MdAsTu3n25yDbIe1NeN69G4n6mUnJGtSJHygX3+oN0ZbO3DTiATnf7XnYJdGT42JCXurTb1JI0qOBR65shvhPQ==" + }, + "node_modules/should-type-adaptors": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/should-type-adaptors/-/should-type-adaptors-1.1.0.tgz", + "integrity": "sha512-JA4hdoLnN+kebEp2Vs8eBe9g7uy0zbRo+RMcU0EsNy+R+k049Ki+N5tT5Jagst2g7EAja+euFuoXFCa8vIklfA==", + "dependencies": { + "should-type": "^1.3.0", + "should-util": "^1.0.0" + } + }, + "node_modules/should-util": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/should-util/-/should-util-1.0.1.tgz", + "integrity": "sha512-oXF8tfxx5cDk8r2kYqlkUJzZpDBqVY/II2WhvU0n9Y3XYvAYRmeaf1PvvIvTgPnv4KJ+ES5M0PyDq5Jp+Ygy2g==" + }, + "node_modules/string-width": { + "version": "4.2.3", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", + "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", + "dependencies": { + "emoji-regex": "^8.0.0", + "is-fullwidth-code-point": "^3.0.0", + "strip-ansi": "^6.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "dependencies": { + "ansi-regex": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/supports-color": { + "version": "5.5.0", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-5.5.0.tgz", + "integrity": "sha512-QjVjwdXIt408MIiAqCX4oUKsgU2EqAGzs2Ppkm4aQYbjm+ZEWEcW4SfFNTr4uMNZma0ey4f5lgLrkB0aX0QMow==", + "dependencies": { + "has-flag": "^3.0.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/swagger2openapi": { + "version": "7.0.8", + "resolved": "https://registry.npmjs.org/swagger2openapi/-/swagger2openapi-7.0.8.tgz", + "integrity": "sha512-upi/0ZGkYgEcLeGieoz8gT74oWHA0E7JivX7aN9mAf+Tc7BQoRBvnIGHoPDw+f9TXTW4s6kGYCZJtauP6OYp7g==", + "dependencies": { + "call-me-maybe": "^1.0.1", + "node-fetch": "^2.6.1", + "node-fetch-h2": "^2.3.0", + "node-readfiles": "^0.2.0", + "oas-kit-common": "^1.0.8", + "oas-resolver": "^2.5.6", + "oas-schema-walker": "^1.1.5", + "oas-validator": "^5.0.8", + "reftools": "^1.1.9", + "yaml": "^1.10.0", + "yargs": "^17.0.1" + }, + "bin": { + "boast": "boast.js", + "oas-validate": "oas-validate.js", + "swagger2openapi": "swagger2openapi.js" + }, + "funding": { + "url": "https://github.com/Mermade/oas-kit?sponsor=1" + } + }, + "node_modules/swagger2openapi/node_modules/yaml": { + "version": "1.10.2", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.2.tgz", + "integrity": "sha512-r3vXyErRCYJ7wg28yvBY5VSoAF8ZvlcW9/BwUzEtUsjvX/DKs24dIkuwjtuprwJJHsbyUbLApepYTR1BN4uHrg==", + "engines": { + "node": ">= 6" + } + }, + "node_modules/tr46": { + "version": "0.0.3", + "resolved": "https://registry.npmjs.org/tr46/-/tr46-0.0.3.tgz", + "integrity": "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==" + }, + "node_modules/webidl-conversions": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-3.0.1.tgz", + "integrity": "sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ==" + }, + "node_modules/whatwg-url": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-5.0.0.tgz", + "integrity": "sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==", + "dependencies": { + "tr46": "~0.0.3", + "webidl-conversions": "^3.0.0" + } + }, + "node_modules/which-module": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/which-module/-/which-module-2.0.0.tgz", + "integrity": "sha512-B+enWhmw6cjfVC7kS8Pj9pCrKSc5txArRyaYGe088shv/FGWH+0Rjx/xPgtsWfsUtS27FkP697E4DDhgrgoc0Q==" + }, + "node_modules/wrap-ansi": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz", + "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==", + "dependencies": { + "ansi-styles": "^4.0.0", + "string-width": "^4.1.0", + "strip-ansi": "^6.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/chalk/wrap-ansi?sponsor=1" + } + }, + "node_modules/y18n": { + "version": "5.0.8", + "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz", + "integrity": "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==", + "engines": { + "node": ">=10" + } + }, + "node_modules/yaml": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.1.3.tgz", + "integrity": "sha512-AacA8nRULjKMX2DvWvOAdBZMOfQlypSFkjcOcu9FalllIDJ1kvlREzcdIZmidQUqqeMv7jorHjq2HlLv/+c2lg==", + "engines": { + "node": ">= 14" + } + }, + "node_modules/yargs": { + "version": "17.6.2", + "resolved": "https://registry.npmjs.org/yargs/-/yargs-17.6.2.tgz", + "integrity": "sha512-1/9UrdHjDZc0eOU0HxOHoS78C69UD3JRMvzlJ7S79S2nTaWRA/whGCTV8o9e/N/1Va9YIV7Q4sOxD8VV4pCWOw==", + "dependencies": { + "cliui": "^8.0.1", + "escalade": "^3.1.1", + "get-caller-file": "^2.0.5", + "require-directory": "^2.1.1", + "string-width": "^4.2.3", + "y18n": "^5.0.5", + "yargs-parser": "^21.1.1" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/yargs-parser": { + "version": "21.1.1", + "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-21.1.1.tgz", + "integrity": "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==", + "engines": { + "node": ">=12" + } + } + }, + "dependencies": { + "@exodus/schemasafe": { + "version": "1.0.0-rc.9", + "resolved": "https://registry.npmjs.org/@exodus/schemasafe/-/schemasafe-1.0.0-rc.9.tgz", + "integrity": "sha512-dGGHpb61hLwifAu7sotuHFDBw6GTdpG8aKC0fsK17EuTzMRvUrH7lEAr6LTJ+sx3AZYed9yZ77rltVDHyg2hRg==" + }, + "abbrev": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/abbrev/-/abbrev-1.1.1.tgz", + "integrity": "sha512-nne9/IiQ/hzIhY6pdDnbBtz7DjPTKrY00P/zvPSm5pOFkl6xuGrGnXn/VtTNNfNtAfZ9/1RtehkszU9qcTii0Q==" + }, + "ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==" + }, + "ansi-styles": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", + "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", + "requires": { + "color-convert": "^2.0.1" + } + }, + "balanced-match": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz", + "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==" + }, + "brace-expansion": { + "version": "1.1.11", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz", + "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==", + "requires": { + "balanced-match": "^1.0.0", + "concat-map": "0.0.1" + } + }, + "call-me-maybe": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/call-me-maybe/-/call-me-maybe-1.0.2.tgz", + "integrity": "sha512-HpX65o1Hnr9HH25ojC1YGs7HCQLq0GCOibSaWER0eNpgJ/Z1MZv2mTc7+xh6WOPxbRVcmgbv4hGU+uSQ/2xFZQ==" + }, + "camelcase": { + "version": "5.3.1", + "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-5.3.1.tgz", + "integrity": "sha512-L28STB170nwWS63UjtlEOE3dldQApaJXZkOI1uMFfzf3rRuPegHaHesyee+YxQ+W6SvRDQV6UrdOdRiR153wJg==" + }, + "chalk": { + "version": "2.4.2", + "resolved": "https://registry.npmjs.org/chalk/-/chalk-2.4.2.tgz", + "integrity": "sha512-Mti+f9lpJNcwF4tWV8/OrTTtF1gZi+f8FqlyAdouralcFWFQWF2+NgCHShjkCb+IFBLq9buZwE1xckQU4peSuQ==", + "requires": { + "ansi-styles": "^3.2.1", + "escape-string-regexp": "^1.0.5", + "supports-color": "^5.3.0" + }, + "dependencies": { + "ansi-styles": { + "version": "3.2.1", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-3.2.1.tgz", + "integrity": "sha512-VT0ZI6kZRdTh8YyJw3SMbYm/u+NqfsAxEpWO0Pf9sq8/e94WxxOpPKx9FR1FlyCtOVDNOQ+8ntlqFxiRc+r5qA==", + "requires": { + "color-convert": "^1.9.0" + } + }, + "color-convert": { + "version": "1.9.3", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-1.9.3.tgz", + "integrity": "sha512-QfAUtd+vFdAtFQcC8CCyYt1fYWxSqAiK2cSD6zDB8N3cpsEBAvRxp9zOGg6G/SHHJYAT88/az/IuDGALsNVbGg==", + "requires": { + "color-name": "1.1.3" + } + }, + "color-name": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.3.tgz", + "integrity": "sha512-72fSenhMw2HZMTVHeCA9KCmpEIbzWiQsjN+BHcBbS9vr1mtt+vJjPdksIBNUmKAW8TFUDPJK5SUU3QhE9NEXDw==" + } + } + }, + "cliui": { + "version": "8.0.1", + "resolved": "https://registry.npmjs.org/cliui/-/cliui-8.0.1.tgz", + "integrity": "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==", + "requires": { + "string-width": "^4.2.0", + "strip-ansi": "^6.0.1", + "wrap-ansi": "^7.0.0" + } + }, + "color-convert": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", + "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", + "requires": { + "color-name": "~1.1.4" + } + }, + "color-name": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", + "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==" + }, + "concat-map": { + "version": "0.0.1", + "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz", + "integrity": "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==" + }, + "decamelize": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/decamelize/-/decamelize-1.2.0.tgz", + "integrity": "sha512-z2S+W9X73hAUUki+N+9Za2lBlun89zigOyGrsax+KUQ6wKW4ZoWpEYBkGhQjwAjjDCkWxhY0VKEhk8wzY7F5cA==" + }, + "emoji-regex": { + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz", + "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==" + }, + "es6-promise": { + "version": "3.3.1", + "resolved": "https://registry.npmjs.org/es6-promise/-/es6-promise-3.3.1.tgz", + "integrity": "sha512-SOp9Phqvqn7jtEUxPWdWfWoLmyt2VaJ6MpvP9Comy1MceMXqE6bxvaTu4iaxpYYPzhny28Lc+M87/c2cPK6lDg==" + }, + "escalade": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.1.1.tgz", + "integrity": "sha512-k0er2gUkLf8O0zKJiAhmkTnJlTvINGv7ygDNPbeIsX/TJjGJZHuh9B2UxbsaEkmlEo9MfhrSzmhIlhRlI2GXnw==" + }, + "escape-string-regexp": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-1.0.5.tgz", + "integrity": "sha512-vbRorB5FUQWvla16U8R/qgaFIya2qGzwDrNmCZuYKrbdSUMG6I1ZCGQRefkRVhuOkIGVne7BQ35DSfo1qvJqFg==" + }, + "fast-safe-stringify": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/fast-safe-stringify/-/fast-safe-stringify-2.1.1.tgz", + "integrity": "sha512-W+KJc2dmILlPplD/H4K9l9LcAHAfPtP6BY84uVLXQ6Evcz9Lcg33Y2z1IVblT6xdY54PXYVHEv+0Wpq8Io6zkA==" + }, + "find-up": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/find-up/-/find-up-4.1.0.tgz", + "integrity": "sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw==", + "requires": { + "locate-path": "^5.0.0", + "path-exists": "^4.0.0" + } + }, + "get-caller-file": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz", + "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==" + }, + "has-flag": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-3.0.0.tgz", + "integrity": "sha512-sKJf1+ceQBr4SMkvQnBDNDtf4TXpVhVGateu0t918bl30FnbE2m4vNLX+VWe/dpjlb+HugGYzW7uQXH98HPEYw==" + }, + "http2-client": { + "version": "1.3.5", + "resolved": "https://registry.npmjs.org/http2-client/-/http2-client-1.3.5.tgz", + "integrity": "sha512-EC2utToWl4RKfs5zd36Mxq7nzHHBuomZboI0yYL6Y0RmBgT7Sgkq4rQ0ezFTYoIsSs7Tm9SJe+o2FcAg6GBhGA==" + }, + "is-fullwidth-code-point": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", + "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==" + }, + "locate-path": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-5.0.0.tgz", + "integrity": "sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g==", + "requires": { + "p-locate": "^4.1.0" + } + }, + "minimatch": { + "version": "3.0.5", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.0.5.tgz", + "integrity": "sha512-tUpxzX0VAzJHjLu0xUfFv1gwVp9ba3IOuRAVH2EGuRW8a5emA2FlACLqiT/lDVtS1W+TGNwqz3sWaNyLgDJWuw==", + "requires": { + "brace-expansion": "^1.1.7" + } + }, + "node-fetch": { + "version": "2.6.7", + "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.6.7.tgz", + "integrity": "sha512-ZjMPFEfVx5j+y2yF35Kzx5sF7kDzxuDj6ziH4FFbOp87zKDZNx8yExJIb05OGF4Nlt9IHFIMBkRl41VdvcNdbQ==", + "requires": { + "whatwg-url": "^5.0.0" + } + }, + "node-fetch-h2": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/node-fetch-h2/-/node-fetch-h2-2.3.0.tgz", + "integrity": "sha512-ofRW94Ab0T4AOh5Fk8t0h8OBWrmjb0SSB20xh1H8YnPV9EJ+f5AMoYSUQ2zgJ4Iq2HAK0I2l5/Nequ8YzFS3Hg==", + "requires": { + "http2-client": "^1.2.5" + } + }, + "node-readfiles": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/node-readfiles/-/node-readfiles-0.2.0.tgz", + "integrity": "sha512-SU00ZarexNlE4Rjdm83vglt5Y9yiQ+XI1XpflWlb7q7UTN1JUItm69xMeiQCTxtTfnzt+83T8Cx+vI2ED++VDA==", + "requires": { + "es6-promise": "^3.2.1" + } + }, + "nopt": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/nopt/-/nopt-3.0.2.tgz", + "integrity": "sha512-WoB9oKq8r03hlIeU/PvXzsE2XaI97VQMSbw+8YoybgGI/Mow+qeFi7TDpVLCFEBaAhnp8uj5f7kQsuTgTCjRFA==", + "requires": { + "abbrev": "1" + } + }, + "oas-kit-common": { + "version": "1.0.8", + "resolved": "https://registry.npmjs.org/oas-kit-common/-/oas-kit-common-1.0.8.tgz", + "integrity": "sha512-pJTS2+T0oGIwgjGpw7sIRU8RQMcUoKCDWFLdBqKB2BNmGpbBMH2sdqAaOXUg8OzonZHU0L7vfJu1mJFEiYDWOQ==", + "requires": { + "fast-safe-stringify": "^2.0.7" + } + }, + "oas-linter": { + "version": "3.2.2", + "resolved": "https://registry.npmjs.org/oas-linter/-/oas-linter-3.2.2.tgz", + "integrity": "sha512-KEGjPDVoU5K6swgo9hJVA/qYGlwfbFx+Kg2QB/kd7rzV5N8N5Mg6PlsoCMohVnQmo+pzJap/F610qTodKzecGQ==", + "requires": { + "@exodus/schemasafe": "^1.0.0-rc.2", + "should": "^13.2.1", + "yaml": "^1.10.0" + }, + "dependencies": { + "yaml": { + "version": "1.10.2", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.2.tgz", + "integrity": "sha512-r3vXyErRCYJ7wg28yvBY5VSoAF8ZvlcW9/BwUzEtUsjvX/DKs24dIkuwjtuprwJJHsbyUbLApepYTR1BN4uHrg==" + } + } + }, + "oas-resolver": { + "version": "2.5.6", + "resolved": "https://registry.npmjs.org/oas-resolver/-/oas-resolver-2.5.6.tgz", + "integrity": "sha512-Yx5PWQNZomfEhPPOphFbZKi9W93CocQj18NlD2Pa4GWZzdZpSJvYwoiuurRI7m3SpcChrnO08hkuQDL3FGsVFQ==", + "requires": { + "node-fetch-h2": "^2.3.0", + "oas-kit-common": "^1.0.8", + "reftools": "^1.1.9", + "yaml": "^1.10.0", + "yargs": "^17.0.1" + }, + "dependencies": { + "yaml": { + "version": "1.10.2", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.2.tgz", + "integrity": "sha512-r3vXyErRCYJ7wg28yvBY5VSoAF8ZvlcW9/BwUzEtUsjvX/DKs24dIkuwjtuprwJJHsbyUbLApepYTR1BN4uHrg==" + } + } + }, + "oas-schema-walker": { + "version": "1.1.5", + "resolved": "https://registry.npmjs.org/oas-schema-walker/-/oas-schema-walker-1.1.5.tgz", + "integrity": "sha512-2yucenq1a9YPmeNExoUa9Qwrt9RFkjqaMAA1X+U7sbb0AqBeTIdMHky9SQQ6iN94bO5NW0W4TRYXerG+BdAvAQ==" + }, + "oas-validator": { + "version": "5.0.8", + "resolved": "https://registry.npmjs.org/oas-validator/-/oas-validator-5.0.8.tgz", + "integrity": "sha512-cu20/HE5N5HKqVygs3dt94eYJfBi0TsZvPVXDhbXQHiEityDN+RROTleefoKRKKJ9dFAF2JBkDHgvWj0sjKGmw==", + "requires": { + "call-me-maybe": "^1.0.1", + "oas-kit-common": "^1.0.8", + "oas-linter": "^3.2.2", + "oas-resolver": "^2.5.6", + "oas-schema-walker": "^1.1.5", + "reftools": "^1.1.9", + "should": "^13.2.1", + "yaml": "^1.10.0" + }, + "dependencies": { + "yaml": { + "version": "1.10.2", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.2.tgz", + "integrity": "sha512-r3vXyErRCYJ7wg28yvBY5VSoAF8ZvlcW9/BwUzEtUsjvX/DKs24dIkuwjtuprwJJHsbyUbLApepYTR1BN4uHrg==" + } + } + }, + "p-limit": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-2.3.0.tgz", + "integrity": "sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==", + "requires": { + "p-try": "^2.0.0" + } + }, + "p-locate": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-4.1.0.tgz", + "integrity": "sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A==", + "requires": { + "p-limit": "^2.2.0" + } + }, + "p-try": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/p-try/-/p-try-2.2.0.tgz", + "integrity": "sha512-R4nPAVTAU0B9D35/Gk3uJf/7XYbQcyohSKdvAxIRSNghFl4e71hVoGnBNQz9cWaXxO2I10KTC+3jMdvvoKw6dQ==" + }, + "path-exists": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-4.0.0.tgz", + "integrity": "sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==" + }, + "reftools": { + "version": "1.1.9", + "resolved": "https://registry.npmjs.org/reftools/-/reftools-1.1.9.tgz", + "integrity": "sha512-OVede/NQE13xBQ+ob5CKd5KyeJYU2YInb1bmV4nRoOfquZPkAkxuOXicSe1PvqIuZZ4kD13sPKBbR7UFDmli6w==" + }, + "replace": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/replace/-/replace-1.2.2.tgz", + "integrity": "sha512-C4EDifm22XZM2b2JOYe6Mhn+lBsLBAvLbK8drfUQLTfD1KYl/n3VaW/CDju0Ny4w3xTtegBpg8YNSpFJPUDSjA==", + "requires": { + "chalk": "2.4.2", + "minimatch": "3.0.5", + "yargs": "^15.3.1" + }, + "dependencies": { + "cliui": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/cliui/-/cliui-6.0.0.tgz", + "integrity": "sha512-t6wbgtoCXvAzst7QgXxJYqPt0usEfbgQdftEPbLL/cvv6HPE5VgvqCuAIDR0NgU52ds6rFwqrgakNLrHEjCbrQ==", + "requires": { + "string-width": "^4.2.0", + "strip-ansi": "^6.0.0", + "wrap-ansi": "^6.2.0" + } + }, + "wrap-ansi": { + "version": "6.2.0", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-6.2.0.tgz", + "integrity": "sha512-r6lPcBGxZXlIcymEu7InxDMhdW0KDxpLgoFLcguasxCaJ/SOIZwINatK9KY/tf+ZrlywOKU0UDj3ATXUBfxJXA==", + "requires": { + "ansi-styles": "^4.0.0", + "string-width": "^4.1.0", + "strip-ansi": "^6.0.0" + } + }, + "y18n": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/y18n/-/y18n-4.0.3.tgz", + "integrity": "sha512-JKhqTOwSrqNA1NY5lSztJ1GrBiUodLMmIZuLiDaMRJ+itFd+ABVE8XBjOvIWL+rSqNDC74LCSFmlb/U4UZ4hJQ==" + }, + "yargs": { + "version": "15.4.1", + "resolved": "https://registry.npmjs.org/yargs/-/yargs-15.4.1.tgz", + "integrity": "sha512-aePbxDmcYW++PaqBsJ+HYUFwCdv4LVvdnhBy78E57PIor8/OVvhMrADFFEDh8DHDFRv/O9i3lPhsENjO7QX0+A==", + "requires": { + "cliui": "^6.0.0", + "decamelize": "^1.2.0", + "find-up": "^4.1.0", + "get-caller-file": "^2.0.1", + "require-directory": "^2.1.1", + "require-main-filename": "^2.0.0", + "set-blocking": "^2.0.0", + "string-width": "^4.2.0", + "which-module": "^2.0.0", + "y18n": "^4.0.0", + "yargs-parser": "^18.1.2" + } + }, + "yargs-parser": { + "version": "18.1.3", + "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-18.1.3.tgz", + "integrity": "sha512-o50j0JeToy/4K6OZcaQmW6lyXXKhq7csREXcDwk2omFPJEwUNOVtJKvmDr9EI1fAJZUyZcRF7kxGBWmRXudrCQ==", + "requires": { + "camelcase": "^5.0.0", + "decamelize": "^1.2.0" + } + } + } + }, + "require-directory": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz", + "integrity": "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==" + }, + "require-main-filename": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/require-main-filename/-/require-main-filename-2.0.0.tgz", + "integrity": "sha512-NKN5kMDylKuldxYLSUfrbo5Tuzh4hd+2E8NPPX02mZtn1VuREQToYe/ZdlJy+J3uCpfaiGF05e7B8W0iXbQHmg==" + }, + "set-blocking": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/set-blocking/-/set-blocking-2.0.0.tgz", + "integrity": "sha512-KiKBS8AnWGEyLzofFfmvKwpdPzqiy16LvQfK3yv/fVH7Bj13/wl3JSR1J+rfgRE9q7xUJK4qvgS8raSOeLUehw==" + }, + "should": { + "version": "13.2.3", + "resolved": "https://registry.npmjs.org/should/-/should-13.2.3.tgz", + "integrity": "sha512-ggLesLtu2xp+ZxI+ysJTmNjh2U0TsC+rQ/pfED9bUZZ4DKefP27D+7YJVVTvKsmjLpIi9jAa7itwDGkDDmt1GQ==", + "requires": { + "should-equal": "^2.0.0", + "should-format": "^3.0.3", + "should-type": "^1.4.0", + "should-type-adaptors": "^1.0.1", + "should-util": "^1.0.0" + } + }, + "should-equal": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/should-equal/-/should-equal-2.0.0.tgz", + "integrity": "sha512-ZP36TMrK9euEuWQYBig9W55WPC7uo37qzAEmbjHz4gfyuXrEUgF8cUvQVO+w+d3OMfPvSRQJ22lSm8MQJ43LTA==", + "requires": { + "should-type": "^1.4.0" + } + }, + "should-format": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/should-format/-/should-format-3.0.3.tgz", + "integrity": "sha512-hZ58adtulAk0gKtua7QxevgUaXTTXxIi8t41L3zo9AHvjXO1/7sdLECuHeIN2SRtYXpNkmhoUP2pdeWgricQ+Q==", + "requires": { + "should-type": "^1.3.0", + "should-type-adaptors": "^1.0.1" + } + }, + "should-type": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/should-type/-/should-type-1.4.0.tgz", + "integrity": "sha512-MdAsTu3n25yDbIe1NeN69G4n6mUnJGtSJHygX3+oN0ZbO3DTiATnf7XnYJdGT42JCXurTb1JI0qOBR65shvhPQ==" + }, + "should-type-adaptors": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/should-type-adaptors/-/should-type-adaptors-1.1.0.tgz", + "integrity": "sha512-JA4hdoLnN+kebEp2Vs8eBe9g7uy0zbRo+RMcU0EsNy+R+k049Ki+N5tT5Jagst2g7EAja+euFuoXFCa8vIklfA==", + "requires": { + "should-type": "^1.3.0", + "should-util": "^1.0.0" + } + }, + "should-util": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/should-util/-/should-util-1.0.1.tgz", + "integrity": "sha512-oXF8tfxx5cDk8r2kYqlkUJzZpDBqVY/II2WhvU0n9Y3XYvAYRmeaf1PvvIvTgPnv4KJ+ES5M0PyDq5Jp+Ygy2g==" + }, + "string-width": { + "version": "4.2.3", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", + "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", + "requires": { + "emoji-regex": "^8.0.0", + "is-fullwidth-code-point": "^3.0.0", + "strip-ansi": "^6.0.1" + } + }, + "strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "requires": { + "ansi-regex": "^5.0.1" + } + }, + "supports-color": { + "version": "5.5.0", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-5.5.0.tgz", + "integrity": "sha512-QjVjwdXIt408MIiAqCX4oUKsgU2EqAGzs2Ppkm4aQYbjm+ZEWEcW4SfFNTr4uMNZma0ey4f5lgLrkB0aX0QMow==", + "requires": { + "has-flag": "^3.0.0" + } + }, + "swagger2openapi": { + "version": "7.0.8", + "resolved": "https://registry.npmjs.org/swagger2openapi/-/swagger2openapi-7.0.8.tgz", + "integrity": "sha512-upi/0ZGkYgEcLeGieoz8gT74oWHA0E7JivX7aN9mAf+Tc7BQoRBvnIGHoPDw+f9TXTW4s6kGYCZJtauP6OYp7g==", + "requires": { + "call-me-maybe": "^1.0.1", + "node-fetch": "^2.6.1", + "node-fetch-h2": "^2.3.0", + "node-readfiles": "^0.2.0", + "oas-kit-common": "^1.0.8", + "oas-resolver": "^2.5.6", + "oas-schema-walker": "^1.1.5", + "oas-validator": "^5.0.8", + "reftools": "^1.1.9", + "yaml": "^1.10.0", + "yargs": "^17.0.1" + }, + "dependencies": { + "yaml": { + "version": "1.10.2", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.2.tgz", + "integrity": "sha512-r3vXyErRCYJ7wg28yvBY5VSoAF8ZvlcW9/BwUzEtUsjvX/DKs24dIkuwjtuprwJJHsbyUbLApepYTR1BN4uHrg==" + } + } + }, + "tr46": { + "version": "0.0.3", + "resolved": "https://registry.npmjs.org/tr46/-/tr46-0.0.3.tgz", + "integrity": "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==" + }, + "webidl-conversions": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-3.0.1.tgz", + "integrity": "sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ==" + }, + "whatwg-url": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-5.0.0.tgz", + "integrity": "sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==", + "requires": { + "tr46": "~0.0.3", + "webidl-conversions": "^3.0.0" + } + }, + "which-module": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/which-module/-/which-module-2.0.0.tgz", + "integrity": "sha512-B+enWhmw6cjfVC7kS8Pj9pCrKSc5txArRyaYGe088shv/FGWH+0Rjx/xPgtsWfsUtS27FkP697E4DDhgrgoc0Q==" + }, + "wrap-ansi": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz", + "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==", + "requires": { + "ansi-styles": "^4.0.0", + "string-width": "^4.1.0", + "strip-ansi": "^6.0.0" + } + }, + "y18n": { + "version": "5.0.8", + "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz", + "integrity": "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==" + }, + "yaml": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.1.3.tgz", + "integrity": "sha512-AacA8nRULjKMX2DvWvOAdBZMOfQlypSFkjcOcu9FalllIDJ1kvlREzcdIZmidQUqqeMv7jorHjq2HlLv/+c2lg==" + }, + "yargs": { + "version": "17.6.2", + "resolved": "https://registry.npmjs.org/yargs/-/yargs-17.6.2.tgz", + "integrity": "sha512-1/9UrdHjDZc0eOU0HxOHoS78C69UD3JRMvzlJ7S79S2nTaWRA/whGCTV8o9e/N/1Va9YIV7Q4sOxD8VV4pCWOw==", + "requires": { + "cliui": "^8.0.1", + "escalade": "^3.1.1", + "get-caller-file": "^2.0.5", + "require-directory": "^2.1.1", + "string-width": "^4.2.3", + "y18n": "^5.0.5", + "yargs-parser": "^21.1.1" + } + }, + "yargs-parser": { + "version": "21.1.1", + "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-21.1.1.tgz", + "integrity": "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==" + } + } +} diff --git a/scripts/openapi-convert/package.json b/scripts/openapi-convert/package.json new file mode 100644 index 000000000..96574309e --- /dev/null +++ b/scripts/openapi-convert/package.json @@ -0,0 +1,17 @@ +{ + "name": "openapi-convert", + "version": "1.0.0", + "description": "", + "main": "index.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1" + }, + "author": "", + "license": "ISC", + "dependencies": { + "nopt": "^3.0.2", + "replace": "^1.2.2", + "swagger2openapi": "^7.0.8", + "yaml": "^2.1.3" + } +} diff --git a/scripts/openapi-convert/string-fixes.mjs b/scripts/openapi-convert/string-fixes.mjs new file mode 100644 index 000000000..e303550ee --- /dev/null +++ b/scripts/openapi-convert/string-fixes.mjs @@ -0,0 +1,165 @@ +"use strict"; +import fs from 'node:fs/promises'; +import path_utils from 'node:path'; +import yaml from 'yaml'; + +const DEFAULT_INDENT = 2; + +// Find the first child field with the given indentation in the given content. +// +// Returns the position at the end of the field's line. +function findYamlChildField(content, min_indent, field_name) { + const min_indent_string = " ".repeat(min_indent); + const field_line = min_indent_string + field_name + ":\n"; + let line_start_idx = 0; + + while (line_start_idx < content.length) { + const content_end = content.slice(line_start_idx); + const line_length = content_end.indexOf("\n") + 1; + const line_end_idx = line_start_idx + line_length; + const line = content_end.slice(0, line_length); + + if (line == field_line) { + // This is the child we are looking for. + return line_end_idx; + } + + if (!line.startsWith(min_indent_string)) { + // We changed the parent so we can't find the child anymore. + return null; + } + + line_start_idx = line_end_idx; + } + + // We didn't find the child. + return null; +} + +// Find the end of the children with the given indentation in the YAML content. +// +// Returns the position at the end of the last child. +function findYamlChildrenEnd(content, min_indent) { + const min_indent_string = " ".repeat(min_indent); + let line_start_idx = 0; + + while (line_start_idx < content.length) { + const content_end = content.slice(line_start_idx); + + if (content_end.startsWith(min_indent_string)) { + const line_length = content_end.indexOf("\n") + 1; + line_start_idx += line_length; + } else { + break; + } + } + + return line_start_idx; +} + +// Convert and replace the YAML in the given content between start and end with JSON. +function replaceYamlWithJson(content, start, end, extra_indent) { + console.log("Processing example", start, end); + const example_yaml = content.slice(start, end); + console.log("```" + example_yaml + "```"); + const example_obj = yaml.parse(example_yaml); + const example_json = JSON.stringify(example_obj, null, DEFAULT_INDENT) + "\n"; + console.log("```" + example_json + "```"); + + // Fix the indentation. + let json_lines = example_json.split("\n"); + // The first and last line don't need the extra indent. + for (let i = 1; i < json_lines.length - 1; i++) { + json_lines[i] = " ".repeat(extra_indent) + json_lines[i]; + } + const indented_example_json = json_lines.join("\n"); + + // Put the opening bracket on the same line as the parent field. + const replace_start = start - 1; + content = content.slice(0, replace_start) + ' ' + indented_example_json + content.slice(end); + + return content; +} + +/// Convert the examples under the given fields in the YAML content to JSON. +function convertExamplesToJson(content, parent_field, example_field) { + const parent_field_regex_string = "( +)" + parent_field + ":\n"; + const parent_field_regex = RegExp(parent_field_regex_string, 'g'); + let match; + let examples = []; + + while ((match = parent_field_regex.exec(content)) !== null) { + console.log("Found parent field", parent_field, match.index); + const indent_capture = match[1]; + const example_field_line_indent = indent_capture.length + DEFAULT_INDENT; + const parent_field_line_end = parent_field_regex.lastIndex; + let content_end = content.slice(parent_field_line_end); + + const example_field_line_end = findYamlChildField(content_end, example_field_line_indent, example_field); + + if (example_field_line_end == null) { + continue; + } + + const example_start = parent_field_line_end + example_field_line_end; + content_end = content.slice(example_start); + console.log("Found example at", example_start); + const example_line_min_indent = example_field_line_indent + DEFAULT_INDENT; + const example_length = findYamlChildrenEnd(content_end, example_line_min_indent); + console.log("Example length", example_length); + + if (example_length > 0) { + examples.push({ + start: example_start, + end: example_start + example_length, + extra_indent: example_field_line_indent, + }) + } + } + + for (const example of examples.reverse()) { + content = replaceYamlWithJson(content, example.start, example.end, example.extra_indent); + } + + return content; +} + +async function applyStringFixesFile(path) { + const relative_separator = path.lastIndexOf('/data/api'); + const short_path = path.slice(relative_separator + 1); + console.log("%s", short_path); + + let content = await fs.readFile(path, "utf-8"); + + // Fix occurrences of `*xx` status codes to `*XX`. + content = content.replaceAll("3xx:", "\"3XX\":"); + content = content.replaceAll("4xx:", "\"4XX\":"); + + // Fix occurrences of `_ref` to `$ref`. + content = content.replaceAll("_ref:", "$ref:"); + + // Fix occurrences of `x-example` to `example`. + content = content.replaceAll("x-example:", "example:"); + + // Convert examples back to JSON. + // Response examples. + content = convertExamplesToJson(content, "response", "value"); + // Schema examples. + content = convertExamplesToJson(content, "schema", "example"); + + await fs.writeFile(path, content); +} + +// Fixes to apply to the string content of the files. +export async function applyStringFixes(path) { + const stat = await fs.lstat(path); + if (stat.isDirectory()) { + const files = await fs.readdir(path); + + for (const file of files) { + await applyStringFixes(path_utils.join(path, file)) + } + } else if (stat.isFile()) { + await applyStringFixesFile(path); + } +} \ No newline at end of file From 10603b43c3865a593d13df144f3818f851e5e350 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Tue, 9 May 2023 15:40:01 +0200 Subject: [PATCH 2/7] Automatic conversion of API files to OpenAPI 3.1.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- data/api/application-service/protocols.yaml | 391 +++-- data/api/application-service/query_room.yaml | 104 +- data/api/application-service/query_user.yaml | 104 +- .../api/application-service/transactions.yaml | 89 +- data/api/client-server/account-data.yaml | 395 +++-- data/api/client-server/admin.yaml | 156 +- .../client-server/administrative_contact.yaml | 735 +++++---- .../appservice_room_directory.yaml | 91 +- data/api/client-server/banning.yaml | 184 ++- data/api/client-server/capabilities.yaml | 169 +- data/api/client-server/content-repo.yaml | 882 ++++++----- data/api/client-server/create_room.yaml | 377 ++--- data/api/client-server/cross_signing.yaml | 363 +++-- .../definitions/push_condition.yaml | 2 +- data/api/client-server/device_management.yaml | 293 ++-- data/api/client-server/directory.yaml | 344 ++-- data/api/client-server/event_context.yaml | 191 +-- data/api/client-server/filter.yaml | 265 ++-- data/api/client-server/inviting.yaml | 132 +- data/api/client-server/joining.yaml | 237 +-- data/api/client-server/key_backup.yaml | 1386 +++++++++-------- data/api/client-server/keys.yaml | 770 +++++---- data/api/client-server/kicking.yaml | 102 +- data/api/client-server/knocking.yaml | 148 +- data/api/client-server/leaving.yaml | 140 +- data/api/client-server/list_joined_rooms.yaml | 74 +- data/api/client-server/list_public_rooms.yaml | 279 ++-- data/api/client-server/login.yaml | 389 ++--- data/api/client-server/logout.yaml | 56 +- .../api/client-server/message_pagination.yaml | 210 +-- data/api/client-server/notifications.yaml | 193 +-- data/api/client-server/old_sync.yaml | 485 +++--- data/api/client-server/openid.yaml | 81 +- data/api/client-server/peeking_events.yaml | 125 +- data/api/client-server/presence.yaml | 189 ++- data/api/client-server/profile.yaml | 282 ++-- data/api/client-server/pusher.yaml | 463 +++--- data/api/client-server/pushrules.yaml | 1080 +++++++------ data/api/client-server/read_markers.yaml | 119 +- data/api/client-server/receipts.yaml | 130 +- data/api/client-server/redaction.yaml | 94 +- data/api/client-server/refresh.yaml | 145 +- data/api/client-server/registration.yaml | 848 +++++----- .../client-server/registration_tokens.yaml | 95 +- data/api/client-server/relations.yaml | 471 +++--- data/api/client-server/report_content.yaml | 90 +- .../room_event_by_timestamp.yaml | 134 +- data/api/client-server/room_initial_sync.yaml | 267 ++-- data/api/client-server/room_send.yaml | 98 +- data/api/client-server/room_state.yaml | 131 +- data/api/client-server/room_upgrades.yaml | 133 +- data/api/client-server/rooms.yaml | 370 +++-- data/api/client-server/search.yaml | 604 +++---- data/api/client-server/space_hierarchy.yaml | 267 ++-- .../api/client-server/sso_login_redirect.yaml | 50 +- data/api/client-server/sync.yaml | 813 +++++----- data/api/client-server/tags.yaml | 220 +-- .../api/client-server/third_party_lookup.yaml | 225 +-- .../client-server/third_party_membership.yaml | 131 +- data/api/client-server/threads_list.yaml | 174 ++- data/api/client-server/to_device.yaml | 104 +- data/api/client-server/typing.yaml | 98 +- data/api/client-server/users.yaml | 163 +- data/api/client-server/versions.yaml | 86 +- data/api/client-server/voip.yaml | 111 +- data/api/client-server/wellknown.yaml | 36 +- data/api/client-server/whoami.yaml | 149 +- data/api/identity/v2_associations.yaml | 508 +++--- data/api/identity/v2_auth.yaml | 186 ++- data/api/identity/v2_email_associations.yaml | 239 +-- data/api/identity/v2_invitation_signing.yaml | 184 ++- data/api/identity/v2_lookup.yaml | 231 +-- data/api/identity/v2_phone_associations.yaml | 236 +-- data/api/identity/v2_ping.yaml | 40 +- data/api/identity/v2_pubkey.yaml | 172 +- data/api/identity/v2_store_invite.yaml | 308 ++-- data/api/identity/v2_terms.yaml | 222 +-- data/api/identity/versions.yaml | 64 +- data/api/push-gateway/push_notifier.yaml | 378 ++--- data/api/server-server/backfill.yaml | 170 +- data/api/server-server/event_auth.yaml | 84 +- data/api/server-server/events.yaml | 281 ++-- data/api/server-server/invites-v1.yaml | 245 ++- data/api/server-server/invites-v2.yaml | 273 ++-- data/api/server-server/joins-v1.yaml | 568 +++---- data/api/server-server/joins-v2.yaml | 393 ++--- data/api/server-server/keys_query.yaml | 140 +- data/api/server-server/keys_server.yaml | 35 +- data/api/server-server/knocks.yaml | 488 +++--- data/api/server-server/leaving-v1.yaml | 360 +++-- data/api/server-server/leaving-v2.yaml | 173 +- data/api/server-server/openid.yaml | 78 +- data/api/server-server/public_rooms.yaml | 278 ++-- data/api/server-server/query.yaml | 206 +-- data/api/server-server/space_hierarchy.yaml | 338 ++-- .../api/server-server/third_party_invite.yaml | 535 +++---- data/api/server-server/transactions.yaml | 137 +- data/api/server-server/user_devices.yaml | 174 ++- data/api/server-server/user_keys.yaml | 415 +++-- data/api/server-server/version.yaml | 72 +- data/api/server-server/wellknown.yaml | 72 +- 101 files changed, 14363 insertions(+), 12232 deletions(-) diff --git a/data/api/application-service/protocols.yaml b/data/api/application-service/protocols.yaml index 47f62b8fa..59dff5b01 100644 --- a/data/api/application-service/protocols.yaml +++ b/data/api/application-service/protocols.yaml @@ -11,25 +11,15 @@ # 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 Application Service API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/app/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Application Service API + version: 1.0.0 paths: "/thirdparty/protocol/{protocol}": get: - summary: Retrieve metadata about a specific protocol that the application service supports. + summary: Retrieve metadata about a specific protocol that the application + service supports. description: |- This API is called by the homeserver when it wants to present clients with specific information about the various third-party networks that @@ -40,42 +30,53 @@ paths: parameters: - in: path name: protocol - type: string description: The protocol ID. required: true - x-example: "irc" + example: irc + schema: + type: string responses: - 200: + "200": description: The protocol was found and metadata returned. - schema: - $ref: definitions/protocol.yaml - 401: + content: + application/json: + schema: + $ref: definitions/protocol.yaml + "401": description: |- The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - 403: - description: |- - The credentials supplied by the homeserver were rejected. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - 404: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" + } + "403": + description: The credentials supplied by the homeserver were rejected. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" + } + "404": description: No protocol was found with the given path. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" + } "/thirdparty/user/{protocol}": get: summary: Retrieve the Matrix User ID of a corresponding third-party user. @@ -89,102 +90,126 @@ paths: parameters: - in: path name: protocol - type: string description: The protocol ID. required: true - x-example: irc + example: irc + schema: + type: string - in: query name: fields... - type: string description: |- One or more custom fields that are passed to the application service to help identify the user. + schema: + type: string responses: - 200: + "200": description: The Matrix User IDs found with the given parameters. - schema: - $ref: definitions/user_batch.yaml - 401: + content: + application/json: + schema: + $ref: definitions/user_batch.yaml + "401": description: |- The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - 403: - description: |- - The credentials supplied by the homeserver were rejected. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - 404: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" + } + "403": + description: The credentials supplied by the homeserver were rejected. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" + } + "404": description: No users were found with the given parameters. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" + } "/thirdparty/location/{protocol}": get: summary: Retrieve Matrix-side portal rooms leading to a third-party location. - description: |- - Retrieve a list of Matrix portal rooms that lead to the matched third-party location. + description: Retrieve a list of Matrix portal rooms that lead to the matched + third-party location. operationId: queryLocationByProtocol security: - homeserverAccessToken: [] parameters: - in: path name: protocol - type: string description: The protocol ID. required: true - x-example: irc + example: irc + schema: + type: string - in: query name: fields... - type: string description: |- One or more custom fields that are passed to the application service to help identify the third-party location. + schema: + type: string responses: - 200: + "200": description: At least one portal room was found. - schema: - $ref: definitions/location_batch.yaml - 401: + content: + application/json: + schema: + $ref: definitions/location_batch.yaml + "401": description: |- The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - 403: - description: |- - The credentials supplied by the homeserver were rejected. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - 404: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" + } + "403": + description: The credentials supplied by the homeserver were rejected. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" + } + "404": description: No mappings were found with the given parameters. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - "/thirdparty/location": + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" + } + /thirdparty/location: get: summary: Reverse-lookup third-party locations given a Matrix room alias. description: |- @@ -196,84 +221,118 @@ paths: parameters: - in: query name: alias - type: string description: The Matrix room alias to look up. - responses: - 200: - description: |- - All found third-party locations. schema: - $ref: definitions/location_batch.yaml - 401: + type: string + responses: + "200": + description: All found third-party locations. + content: + application/json: + schema: + $ref: definitions/location_batch.yaml + "401": description: |- The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - 403: - description: |- - The credentials supplied by the homeserver were rejected. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - 404: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" + } + "403": + description: The credentials supplied by the homeserver were rejected. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" + } + "404": description: No mappings were found with the given parameters. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - "/thirdparty/user": + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" + } + /thirdparty/user: get: summary: Reverse-lookup third-party users given a Matrix User ID. - description: |- - Retrieve an array of third-party users from a Matrix User ID. + description: Retrieve an array of third-party users from a Matrix User ID. operationId: queryUserByID security: - homeserverAccessToken: [] parameters: - - in: query + - in: query name: userid - type: string description: The Matrix User ID to look up. - responses: - 200: - description: |- - An array of third-party users. schema: - $ref: definitions/user_batch.yaml - 401: + type: string + responses: + "200": + description: An array of third-party users. + content: + application/json: + schema: + $ref: definitions/user_batch.yaml + "401": description: |- The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - 403: - description: |- - The credentials supplied by the homeserver were rejected. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - 404: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" + } + "403": + description: The credentials supplied by the homeserver were rejected. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" + } + "404": description: No mappings were found with the given parameters. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/app/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/application-service/query_room.yaml b/data/api/application-service/query_room.yaml index 6ddc6234d..b5280e392 100644 --- a/data/api/application-service/query_room.yaml +++ b/data/api/application-service/query_room.yaml @@ -12,21 +12,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 Application Service API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/app/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Application Service API + version: 1.0.0 paths: "/rooms/{roomAlias}": get: @@ -43,48 +32,75 @@ paths: parameters: - in: path name: roomAlias - type: string description: The room alias being queried. required: true - x-example: "#magicforest:example.com" + example: "#magicforest:example.com" + schema: + type: string responses: - 200: + "200": description: |- The application service indicates that this room alias exists. The application service MUST have created a room and associated it with the queried room alias using the client-server API. Additional information about the room such as its name and topic can be set before responding. - examples: - application/json: {} - schema: - type: object - 401: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "401": description: |- The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - 403: - description: |- - The credentials supplied by the homeserver were rejected. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - 404: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" + } + "403": + description: The credentials supplied by the homeserver were rejected. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" + } + "404": description: |- The application service indicates that this room alias does not exist. Optional error information can be included in the body of this response. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/app/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/application-service/query_user.yaml b/data/api/application-service/query_user.yaml index f8fc4ef1c..09503be1f 100644 --- a/data/api/application-service/query_user.yaml +++ b/data/api/application-service/query_user.yaml @@ -12,21 +12,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 Application Service API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/app/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Application Service API + version: 1.0.0 paths: "/users/{userId}": get: @@ -43,45 +32,72 @@ paths: parameters: - in: path name: userId - type: string description: The user ID being queried. required: true - x-example: "@alice:example.com" + example: "@alice:example.com" + schema: + type: string responses: - 200: + "200": description: |- The application service indicates that this user exists. The application service MUST create the user using the client-server API. - examples: - application/json: {} - schema: - type: object - 401: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "401": description: |- The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - 403: - description: |- - The credentials supplied by the homeserver were rejected. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml - 404: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED" + } + "403": + description: The credentials supplied by the homeserver were rejected. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN" + } + "404": description: |- The application service indicates that this user does not exist. Optional error information can be included in the body of this response. - examples: - application/json: { - "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" - } - schema: - $ref: ../client-server/definitions/errors/error.yaml + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND" + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/app/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/application-service/transactions.yaml b/data/api/application-service/transactions.yaml index de082904f..473def4b2 100644 --- a/data/api/application-service/transactions.yaml +++ b/data/api/application-service/transactions.yaml @@ -12,19 +12,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 Application Service API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/app/v1 -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Application Service API + version: 1.0.0 paths: "/transactions/{txnId}": put: @@ -42,35 +33,59 @@ paths: parameters: - in: path name: txnId - type: string description: |- The transaction ID for this set of events. Homeservers generate these IDs and they are used to ensure idempotency of requests. required: true - x-example: "35" - - in: body - name: body - description: Transaction information + example: "35" schema: - type: object - example: { - "events": [ - {"$ref": "../../event-schemas/examples/m.room.member.yaml"}, - {"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"} - ] - } - properties: - events: - type: array - description: |- - A list of events, formatted as per the Client-Server API. - items: - $ref: "../client-server/definitions/client_event.yaml" - required: ["events"] + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { + "events": [ + { + "$ref": "../../event-schemas/examples/m.room.member.yaml" + }, + { + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + } + ] + } + properties: + events: + type: array + description: A list of events, formatted as per the Client-Server API. + items: + $ref: ../client-server/definitions/client_event.yaml + required: + - events + description: Transaction information responses: - 200: + "200": description: The transaction was processed successfully. - examples: - application/json: {} - schema: - type: object + content: + application/json: + schema: + type: object + examples: + response: + value: {} +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/app/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/account-data.yaml b/data/api/client-server/account-data.yaml index 57e78c716..b4526198d 100644 --- a/data/api/client-server/account-data.yaml +++ b/data/api/client-server/account-data.yaml @@ -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 Client Config 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 Client Config API + version: 1.0.0 paths: "/user/{userId}/account_data/{type}": put: @@ -40,71 +29,85 @@ paths: - accessToken: [] parameters: - in: path - type: string name: userId required: true description: |- The ID of the user to set account data for. The access token must be authorized to make requests for this user ID. - x-example: "@alice:example.com" + example: "@alice:example.com" + schema: + type: string - in: path - type: string name: type required: true description: |- The event type of the account data to set. Custom types should be namespaced to avoid clashes. - x-example: "org.example.custom.config" - - in: body - name: content - required: true - description: |- - The content of the account data. + example: org.example.custom.config schema: - type: object - example: { - "custom_account_data_key": "custom_config_value"} + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { + "custom_account_data_key": "custom_config_value" + } + description: The content of the account data. + required: true responses: - 200: - description: - The account data was successfully added. - examples: - application/json: {} - schema: - type: object - 400: + "200": + description: The account data was successfully added. + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "400": description: |- The request body is not a JSON object. Errcode: `M_BAD_JSON` or `M_NOT_JSON`. - examples: - application/json: { - "errcode": "M_NOT_JSON", - "error": "Content must be a JSON object." - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 403: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_JSON", + "error": "Content must be a JSON object." + } + "403": description: |- The access token provided is not authorized to modify this user's account data. Errcode: `M_FORBIDDEN`. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "Cannot add account data for other users." - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 405: - examples: - application/json: { - "errcode": "M_BAD_JSON", - "error": "Cannot set m.fully_read through this API." - } + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "Cannot add account data for other users." + } + "405": description: |- This `type` of account data is controlled by the server; it cannot be modified by clients. Errcode: `M_BAD_JSON`. - schema: - $ref: "../client-server/definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_BAD_JSON", + "error": "Cannot set m.fully_read through this API." + } tags: - User data get: @@ -117,51 +120,61 @@ paths: - accessToken: [] parameters: - in: path - type: string name: userId required: true description: |- The ID of the user to get account data for. The access token must be authorized to make requests for this user ID. - x-example: "@alice:example.com" + example: "@alice:example.com" + schema: + type: string - in: path - type: string name: type required: true description: |- The event type of the account data to get. Custom types should be namespaced to avoid clashes. - x-example: "org.example.custom.config" - responses: - 200: - description: - The account data content for the given type. + example: org.example.custom.config schema: - type: object - example: { - "custom_account_data_key": "custom_config_value"} - 403: + type: string + responses: + "200": + description: The account data content for the given type. + content: + application/json: + schema: + type: object + example: { + "custom_account_data_key": "custom_config_value" + } + "403": description: |- The access token provided is not authorized to retrieve this user's account data. Errcode: `M_FORBIDDEN`. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "Cannot add account data for other users." - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 404: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "Cannot add account data for other users." + } + "404": description: |- No account data has been provided for this user with the given `type`. Errcode: `M_NOT_FOUND`. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Account data not found." - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Account data not found." + } tags: - User data "/user/{userId}/rooms/{roomId}/account_data/{type}": @@ -176,79 +189,93 @@ paths: - accessToken: [] parameters: - in: path - type: string name: userId required: true description: |- The ID of the user to set account data for. The access token must be authorized to make requests for this user ID. - x-example: "@alice:example.com" + example: "@alice:example.com" + schema: + type: string - in: path - type: string name: roomId required: true - description: |- - The ID of the room to set account data on. - x-example: "!726s6s6q:example.com" + description: The ID of the room to set account data on. + example: "!726s6s6q:example.com" + schema: + type: string - in: path - type: string name: type required: true description: |- The event type of the account data to set. Custom types should be namespaced to avoid clashes. - x-example: "org.example.custom.room.config" - - in: body - name: content - required: true - description: |- - The content of the account data. + example: org.example.custom.room.config schema: - type: object - example: { - "custom_account_data_key": "custom_account_data_value"} + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { + "custom_account_data_key": "custom_account_data_value" + } + description: The content of the account data. + required: true responses: - 200: - description: - The account data was successfully added. - examples: - application/json: {} - schema: - type: object - 400: + "200": + description: The account data was successfully added. + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "400": description: |- The request body is not a JSON object (errcode `M_BAD_JSON` or `M_NOT_JSON`), or the given `roomID` is not a valid room ID (errcode `M_INVALID_PARAM`). - examples: - application/json: { - "errcode": "M_NOT_JSON", - "error": "Content must be a JSON object." - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 403: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_JSON", + "error": "Content must be a JSON object." + } + "403": description: |- The access token provided is not authorized to modify this user's account data. Errcode: `M_FORBIDDEN`. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "Cannot add account data for other users." - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 405: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "Cannot add account data for other users." + } + "405": description: |- This `type` of account data is controlled by the server; it cannot be modified by clients. Errcode: `M_BAD_JSON`. - examples: - application/json: { - "errcode": "M_BAD_JSON", - "error": "Cannot set m.fully_read through this API." - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_BAD_JSON", + "error": "Cannot set m.fully_read through this API." + } tags: - User data get: @@ -261,65 +288,93 @@ paths: - accessToken: [] parameters: - in: path - type: string name: userId required: true description: |- The ID of the user to get account data for. The access token must be authorized to make requests for this user ID. - x-example: "@alice:example.com" + example: "@alice:example.com" + schema: + type: string - in: path - type: string name: roomId required: true - description: |- - The ID of the room to get account data for. - x-example: "!726s6s6q:example.com" + description: The ID of the room to get account data for. + example: "!726s6s6q:example.com" + schema: + type: string - in: path - type: string name: type required: true description: |- The event type of the account data to get. Custom types should be namespaced to avoid clashes. - x-example: "org.example.custom.room.config" - responses: - 200: - description: - The account data content for the given type. + example: org.example.custom.room.config schema: - type: object - example: { - "custom_account_data_key": "custom_config_value"} - 400: - description: |- - The given `roomID` is not a valid room ID. Errcode: `M_INVALID_PARAM`. - examples: - application/json: { - "errcode": "M_INVALID_PARAM", - "error": "@notaroomid:example.org is not a valid room ID." - } - 403: + type: string + responses: + "200": + description: The account data content for the given type. + content: + application/json: + schema: + type: object + example: { + "custom_account_data_key": "custom_config_value" + } + "400": + description: "The given `roomID` is not a valid room ID. Errcode: + `M_INVALID_PARAM`." + content: + application/json: + examples: + response: + value: { + "errcode": "M_INVALID_PARAM", + "error": "@notaroomid:example.org is not a valid room ID." + } + "403": description: |- The access token provided is not authorized to retrieve this user's account data. Errcode: `M_FORBIDDEN`. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "Cannot add account data for other users." - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 404: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "Cannot add account data for other users." + } + "404": description: |- No account data has been provided for this user and this room with the given `type`. Errcode: `M_NOT_FOUND`. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Room account data not found." - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Room account data not found." + } tags: - User data +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 diff --git a/data/api/client-server/admin.yaml b/data/api/client-server/admin.yaml index 403be39f2..ec92eadb0 100644 --- a/data/api/client-server/admin.yaml +++ b/data/api/client-server/admin.yaml @@ -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 Administration 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 Administration API + version: 1.0.0 paths: "/admin/whois/{userId}": get: @@ -41,75 +30,94 @@ paths: - accessToken: [] parameters: - in: path - type: string name: userId description: The user to look up. required: true - x-example: "@peter:rabbit.rocks" + example: "@peter:rabbit.rocks" + schema: + type: string responses: - 200: + "200": description: The lookup was successful. - examples: - application/json: { - "user_id": "@peter:rabbit.rocks", - "devices": { - "teapot": { - "sessions": [ - { - "connections": [ - { - "ip": "127.0.0.1", - "last_seen": 1411996332123, - "user_agent": "curl/7.31.0-DEV" - }, + content: + application/json: + schema: + type: object + properties: + user_id: + type: string + description: The Matrix user ID of the user. + devices: + type: object + description: Each key is an identifier for one of the user's devices. + additionalProperties: + type: object + title: DeviceInfo + properties: + sessions: + type: array + description: A user's sessions (i.e. what they did with an access token from one + login). + items: + type: object + title: SessionInfo + properties: + connections: + type: array + description: Information particular connections in the session. + items: + type: object + title: ConnectionInfo + properties: + ip: + type: string + description: Most recently seen IP address of the session. + last_seen: + type: integer + format: int64 + description: Unix timestamp that the session was last active. + user_agent: + type: string + description: User agent string last seen in the session. + examples: + response: + value: { + "user_id": "@peter:rabbit.rocks", + "devices": { + "teapot": { + "sessions": [ { - "ip": "10.0.0.2", - "last_seen": 1411996332123, - "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.120 Safari/537.36" + "connections": [ + { + "ip": "127.0.0.1", + "last_seen": 1411996332123, + "user_agent": "curl/7.31.0-DEV" + }, + { + "ip": "10.0.0.2", + "last_seen": 1411996332123, + "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.120 Safari/537.36" + } + ] } ] } - ] + } } - } - } - schema: - type: object - properties: - user_id: - type: string - description: The Matrix user ID of the user. - devices: - type: object - description: |- - Each key is an identifier for one of the user's devices. - additionalProperties: - type: object - title: DeviceInfo - properties: - sessions: - type: array - description: A user's sessions (i.e. what they did with an access token from one login). - items: - type: object - title: SessionInfo - properties: - connections: - type: array - description: Information particular connections in the session. - items: - type: object - title: ConnectionInfo - properties: - ip: - type: string - description: Most recently seen IP address of the session. - last_seen: - type: integer - format: int64 - description: Unix timestamp that the session was last active. - user_agent: - type: string - description: User agent string last seen in the session. tags: - Server administration +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 diff --git a/data/api/client-server/administrative_contact.yaml b/data/api/client-server/administrative_contact.yaml index fd6adc94d..f2adefd18 100644 --- a/data/api/client-server/administrative_contact.yaml +++ b/data/api/client-server/administrative_contact.yaml @@ -12,23 +12,12 @@ # 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 Account Administrative Contact 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 Account Administrative Contact API + version: 1.0.0 paths: - "/account/3pid": + /account/3pid: get: summary: Gets a list of a user's third-party identifiers. description: |- @@ -44,48 +33,56 @@ paths: security: - accessToken: [] responses: - 200: + "200": description: The lookup was successful. - examples: - application/json: { - "threepids": [ - { - "medium": "email", - "address": "monkey@banana.island", - "validated_at": 1535176800000, - "added_at": 1535336848756 - } - ] - } - schema: - type: object - properties: - threepids: - type: array - items: - type: object - title: Third-party identifier - properties: - medium: - type: string - description: The medium of the third-party identifier. - enum: ["email", "msisdn"] - address: - type: string - description: The third-party identifier address. - validated_at: - type: integer - format: int64 - description: |- - The timestamp, in milliseconds, when the identifier was - validated by the identity server. - added_at: - type: integer - format: int64 - description: - The timestamp, in milliseconds, when the homeserver - associated the third-party identifier with the user. - required: ['medium', 'address', 'validated_at', 'added_at'] + content: + application/json: + schema: + type: object + properties: + threepids: + type: array + items: + type: object + title: Third-party identifier + properties: + medium: + type: string + description: The medium of the third-party identifier. + enum: + - email + - msisdn + address: + type: string + description: The third-party identifier address. + validated_at: + type: integer + format: int64 + description: |- + The timestamp, in milliseconds, when the identifier was + validated by the identity server. + added_at: + type: integer + format: int64 + description: The timestamp, in milliseconds, when the homeserver associated the + third-party identifier with the user. + required: + - medium + - address + - validated_at + - added_at + examples: + response: + value: { + "threepids": [ + { + "medium": "email", + "address": "monkey@banana.island", + "validated_at": 1535176800000, + "added_at": 1535336848756 + } + ] + } tags: - Account management post: @@ -105,36 +102,40 @@ paths: deprecated: true security: - accessToken: [] - parameters: - - in: body - name: body - required: true - schema: - type: object - properties: - three_pid_creds: - title: "ThreePidCredentials" - type: object - description: The third-party credentials to associate with the account. - properties: - client_secret: - type: string - description: The client secret used in the session with the identity server. - id_server: - type: string - description: The identity server to use. - id_access_token: - type: string - description: |- - An access token previously registered with the identity server. Servers - can treat this as optional to distinguish between r0.5-compatible clients - and this specification version. - sid: - type: string - description: The session identifier given by the identity server. - required: ["client_secret", "id_server", "id_access_token", "sid"] - required: ["three_pid_creds"] - example: { + requestBody: + content: + application/json: + schema: + type: object + properties: + three_pid_creds: + title: ThreePidCredentials + type: object + description: The third-party credentials to associate with the account. + properties: + client_secret: + type: string + description: The client secret used in the session with the identity server. + id_server: + type: string + description: The identity server to use. + id_access_token: + type: string + description: |- + An access token previously registered with the identity server. Servers + can treat this as optional to distinguish between r0.5-compatible clients + and this specification version. + sid: + type: string + description: The session identifier given by the identity server. + required: + - client_secret + - id_server + - id_access_token + - sid + required: + - three_pid_creds + example: { "three_pid_creds": { "id_server": "matrix.org", "id_access_token": "abc123_OpaqueString", @@ -142,45 +143,52 @@ paths: "client_secret": "d0nt-T3ll" } } + required: true responses: - 200: + "200": description: The addition was successful. - examples: - application/json: { - "submit_url": "https://example.org/path/to/submitToken" - } - schema: - type: object - properties: - submit_url: - type: string - format: uri - description: |- - An optional field containing a URL where the client must - submit the validation token to, with identical parameters - to the Identity Service API's `POST - /validate/email/submitToken` endpoint (without the requirement - for an access token). The homeserver must send this token to the - user (if applicable), who should then be prompted to provide it - to the client. + content: + application/json: + schema: + type: object + properties: + submit_url: + type: string + format: uri + description: |- + An optional field containing a URL where the client must + submit the validation token to, with identical parameters + to the Identity Service API's `POST + /validate/email/submitToken` endpoint (without the requirement + for an access token). The homeserver must send this token to the + user (if applicable), who should then be prompted to provide it + to the client. - If this field is not present, the client can assume that - verification will happen without the client's involvement - provided the homeserver advertises this specification version - in the `/versions` response (ie: r0.5.0). - example: "https://example.org/path/to/submitToken" - 403: + If this field is not present, the client can assume that + verification will happen without the client's involvement + provided the homeserver advertises this specification version + in the `/versions` response (ie: r0.5.0). + example: https://example.org/path/to/submitToken + examples: + response: + value: { + "submit_url": "https://example.org/path/to/submitToken" + } + "403": description: The credentials could not be verified with the identity server. - examples: - application/json: { - "errcode": "M_THREEPID_AUTH_FAILED", - "error": "The third-party credentials could not be verified by the identity server." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_AUTH_FAILED", + "error": "The third-party credentials could not be verified by the identity server." + } tags: - Account management - "/account/3pid/add": + /account/3pid/add: post: summary: Adds contact information to the user's account. description: |- @@ -194,47 +202,55 @@ paths: operationId: add3PID security: - accessToken: [] - parameters: - - in: body - name: body - required: true - schema: - type: object - properties: - auth: - description: |- - Additional authentication information for the - user-interactive authentication API. - allOf: - - $ref: "definitions/auth_data.yaml" - client_secret: - type: string - description: The client secret used in the session with the homeserver. - example: "d0nt-T3ll" - sid: - type: string - description: The session identifier given by the homeserver. - example: "abc123987" - required: ["client_secret", "sid"] + requestBody: + content: + application/json: + schema: + type: object + properties: + auth: + description: |- + Additional authentication information for the + user-interactive authentication API. + allOf: + - $ref: definitions/auth_data.yaml + client_secret: + type: string + description: The client secret used in the session with the homeserver. + example: d0nt-T3ll + sid: + type: string + description: The session identifier given by the homeserver. + example: abc123987 + required: + - client_secret + - sid + required: true responses: - 200: + "200": description: The addition was successful. - examples: - application/json: {} - schema: - type: object - 401: - description: |- - The homeserver requires additional authentication information. - schema: - "$ref": "definitions/auth_response.yaml" - 429: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "401": + description: The homeserver requires additional authentication information. + content: + application/json: + schema: + $ref: definitions/auth_response.yaml + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Account management - "/account/3pid/bind": + /account/3pid/bind: post: summary: Binds a 3PID to the user's account through an Identity Service. description: |- @@ -248,47 +264,55 @@ paths: operationId: bind3PID security: - accessToken: [] - parameters: - - in: body - name: body - required: true - schema: - type: object - properties: - client_secret: - type: string - description: The client secret used in the session with the identity server. - id_server: - type: string - description: The identity server to use. - id_access_token: - type: string - description: |- - An access token previously registered with the identity server. - sid: - type: string - description: The session identifier given by the identity server. - required: ["client_secret", "id_server", "id_access_token", "sid"] - example: { - "id_server": "example.org", - "id_access_token": "abc123_OpaqueString", - "sid": "abc123987", - "client_secret": "d0nt-T3ll" - } + requestBody: + content: + application/json: + schema: + type: object + properties: + client_secret: + type: string + description: The client secret used in the session with the identity server. + id_server: + type: string + description: The identity server to use. + id_access_token: + type: string + description: An access token previously registered with the identity server. + sid: + type: string + description: The session identifier given by the identity server. + required: + - client_secret + - id_server + - id_access_token + - sid + example: { + "id_server": "example.org", + "id_access_token": "abc123_OpaqueString", + "sid": "abc123987", + "client_secret": "d0nt-T3ll" + } + required: true responses: - 200: + "200": description: The addition was successful. - examples: - application/json: {} - schema: - type: object - 429: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Account management - "/account/3pid/delete": + /account/3pid/delete: post: summary: Deletes a third-party identifier from the user's account description: |- @@ -301,59 +325,63 @@ paths: operationId: delete3pidFromAccount security: - accessToken: [] - parameters: - - in: body - name: body - required: true - schema: - type: object - properties: - id_server: - type: string - description: |- + requestBody: + content: + application/json: + schema: + type: object + properties: + id_server: + type: string + description: |- The identity server to unbind from. If not provided, the homeserver MUST use the `id_server` the identifier was added through. If the homeserver does not know the original `id_server`, it MUST return a `id_server_unbind_result` of `no-support`. - example: "example.org" - medium: - type: string - description: The medium of the third-party identifier being removed. - enum: ["email", "msisdn"] - example: "email" - address: - type: string - description: The third-party address being removed. - example: "example@example.org" - required: ['medium', 'address'] + example: example.org + medium: + type: string + description: The medium of the third-party identifier being removed. + enum: + - email + - msisdn + example: email + address: + type: string + description: The third-party address being removed. + example: example@example.org + required: + - medium + - address + required: true responses: - 200: + "200": description: |- The homeserver has disassociated the third-party identifier from the user. - schema: - type: object - properties: - id_server_unbind_result: - type: string - enum: - # XXX: I don't know why, but the order matters here so that "no-support" - # doesn't become "no- support" by the renderer. - - "no-support" - - "success" - description: |- - An indicator as to whether or not the homeserver was able to unbind - the 3PID from the identity server. `success` indicates that the - identity server has unbound the identifier whereas `no-support` - indicates that the identity server refuses to support the request - or the homeserver was not able to determine an identity server to - unbind from. - example: "success" - required: - - id_server_unbind_result + content: + application/json: + schema: + type: object + properties: + id_server_unbind_result: + type: string + enum: + - no-support + - success + description: |- + An indicator as to whether or not the homeserver was able to unbind + the 3PID from the identity server. `success` indicates that the + identity server has unbound the identifier whereas `no-support` + indicates that the identity server refuses to support the request + or the homeserver was not able to determine an identity server to + unbind from. + example: success + required: + - id_server_unbind_result tags: - Account management - "/account/3pid/unbind": + /account/3pid/unbind: post: summary: Removes a user's third-party identifier from an identity server. description: |- @@ -366,60 +394,65 @@ paths: operationId: unbind3pidFromAccount security: - accessToken: [] - parameters: - - in: body - name: body - required: true - schema: - type: object - properties: - id_server: - type: string - description: |- + requestBody: + content: + application/json: + schema: + type: object + properties: + id_server: + type: string + description: |- The identity server to unbind from. If not provided, the homeserver MUST use the `id_server` the identifier was added through. If the homeserver does not know the original `id_server`, it MUST return a `id_server_unbind_result` of `no-support`. - example: "example.org" - medium: - type: string - description: The medium of the third-party identifier being removed. - enum: ["email", "msisdn"] - example: "email" - address: - type: string - description: The third-party address being removed. - example: "example@example.org" - required: ['medium', 'address'] + example: example.org + medium: + type: string + description: The medium of the third-party identifier being removed. + enum: + - email + - msisdn + example: email + address: + type: string + description: The third-party address being removed. + example: example@example.org + required: + - medium + - address + required: true responses: - 200: + "200": description: |- The identity server has disassociated the third-party identifier from the user. - schema: - type: object - properties: - id_server_unbind_result: - type: string - enum: - # XXX: I don't know why, but the order matters here so that "no-support" - # doesn't become "no- support" by the renderer. - - "no-support" - - "success" - description: |- - An indicator as to whether or not the identity server was able to unbind - the 3PID. `success` indicates that the identity server has unbound the - identifier whereas `no-support` indicates that the identity server - refuses to support the request or the homeserver was not able to determine - an identity server to unbind from. - example: "success" - required: - - id_server_unbind_result + content: + application/json: + schema: + type: object + properties: + id_server_unbind_result: + type: string + enum: + - no-support + - success + description: |- + An indicator as to whether or not the identity server was able to unbind + the 3PID. `success` indicates that the identity server has unbound the + identifier whereas `no-support` indicates that the identity server + refuses to support the request or the homeserver was not able to determine + an identity server to unbind from. + example: success + required: + - id_server_unbind_result tags: - Account management - "/account/3pid/email/requestToken": + /account/3pid/email/requestToken: post: - summary: Begins the validation process for an email address for association with the user's account. + summary: Begins the validation process for an email address for association with + the user's account. description: |- The homeserver must check that the given email address is **not** already associated with an account on this homeserver. This API should @@ -430,49 +463,58 @@ paths: the email itself, either by sending a validation email itself or by using a service it has control over. operationId: requestTokenTo3PIDEmail - parameters: - - in: body - name: body - required: true - schema: - $ref: "definitions/request_email_validation.yaml" + requestBody: + content: + application/json: + schema: + $ref: definitions/request_email_validation.yaml + required: true responses: - 200: + "200": description: |- An email was sent to the given address. Note that this may be an email containing the validation token or it may be informing the user of an error. - schema: - $ref: "definitions/request_token_response.yaml" - 403: - description: |- - The homeserver does not allow the third-party identifier as a - contact option. - schema: - $ref: "definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_THREEPID_DENIED", - "error": "Third-party identifier is not allowed" - } - 400: + content: + application/json: + schema: + $ref: definitions/request_token_response.yaml + "400": description: |- The third-party identifier is already in use on the homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED` can be returned if the server does not trust/support the identity server provided in the request. - schema: - $ref: "definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_THREEPID_IN_USE", - "error": "Third-party identifier already in use" - } + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_IN_USE", + "error": "Third-party identifier already in use" + } + "403": + description: |- + The homeserver does not allow the third-party identifier as a + contact option. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_DENIED", + "error": "Third-party identifier is not allowed" + } tags: - Account management - "/account/3pid/msisdn/requestToken": + /account/3pid/msisdn/requestToken: post: - summary: Begins the validation process for a phone number for association with the user's account. + summary: Begins the validation process for a phone number for association with + the user's account. description: |- The homeserver must check that the given phone number is **not** already associated with an account on this homeserver. This API should @@ -483,40 +525,63 @@ paths: the phone number itself, either by sending a validation message itself or by using a service it has control over. operationId: requestTokenTo3PIDMSISDN - parameters: - - in: body - name: body - required: true - schema: - $ref: "definitions/request_msisdn_validation.yaml" + requestBody: + content: + application/json: + schema: + $ref: definitions/request_msisdn_validation.yaml + required: true responses: - 200: + "200": description: An SMS message was sent to the given phone number. - schema: - $ref: "definitions/request_token_response.yaml" - 403: - description: |- - The homeserver does not allow the third-party identifier as a - contact option. - schema: - $ref: "definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_THREEPID_DENIED", - "error": "Third-party identifier is not allowed" - } - 400: + content: + application/json: + schema: + $ref: definitions/request_token_response.yaml + "400": description: |- The third-party identifier is already in use on the homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED` can be returned if the server does not trust/support the identity server provided in the request. - schema: - $ref: "definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_THREEPID_IN_USE", - "error": "Third-party identifier already in use" - } + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_IN_USE", + "error": "Third-party identifier already in use" + } + "403": + description: |- + The homeserver does not allow the third-party identifier as a + contact option. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_DENIED", + "error": "Third-party identifier is not allowed" + } tags: - Account management +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 diff --git a/data/api/client-server/appservice_room_directory.yaml b/data/api/client-server/appservice_room_directory.yaml index 233bf2bd3..98a819536 100644 --- a/data/api/client-server/appservice_room_directory.yaml +++ b/data/api/client-server/appservice_room_directory.yaml @@ -11,28 +11,14 @@ # 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 Application Service Room Directory API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - # Note: this is the same access_token definition used elsewhere in the client - # server API, however this expects an access token for an application service. - $ref: definitions/security.yaml + title: Matrix Client-Server Application Service Room Directory API + version: 1.0.0 paths: "/directory/list/appservice/{networkId}/{roomId}": put: - summary: |- - Updates a room's visibility in the application service's room directory. + summary: Updates a room's visibility in the application service's room directory. description: |- Updates the visibility of a given room on the application service's room directory. @@ -46,43 +32,66 @@ paths: operationId: updateAppserviceRoomDirectoryVisibility parameters: - in: path - type: string name: networkId description: |- The protocol (network) ID to update the room list for. This would have been provided by the application service as being listed as a supported protocol. required: true - x-example: "irc" + example: irc + schema: + type: string - in: path - type: string name: roomId description: The room ID to add to the directory. required: true - x-example: "!somewhere:example.org" - - in: body - name: body - required: true + example: "!somewhere:example.org" schema: - type: object - properties: - visibility: - type: string - enum: ["public", "private"] - description: |- - Whether the room should be visible (public) in the directory - or not (private). - example: "public" - required: ['visibility'] + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + visibility: + type: string + enum: + - public + - private + description: |- + Whether the room should be visible (public) in the directory + or not (private). + example: public + required: + - visibility + required: true security: - # again, this is the appservice's token - not a typical client's - accessToken: [] responses: - 200: + "200": description: The room's directory visibility has been updated. - schema: - type: object - examples: - application/json: {} + content: + application/json: + schema: + type: object + examples: + response: + value: {} tags: - Application service room directory management +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 diff --git a/data/api/client-server/banning.yaml b/data/api/client-server/banning.yaml index b1ba4d026..5185d89ba 100644 --- a/data/api/client-server/banning.yaml +++ b/data/api/client-server/banning.yaml @@ -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 Room Banning 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 Room Banning API + version: 1.0.0 paths: "/rooms/{roomId}/ban": post: @@ -41,51 +30,60 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room identifier (not alias) from which the user should be banned. required: true - x-example: "!e42d8c:matrix.org" - - in: body - name: body - required: true + example: "!e42d8c:matrix.org" schema: - type: object - example: { + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { "reason": "Telling unfunny jokes", "user_id": "@cheeky_monkey:matrix.org" } - properties: - user_id: - type: string - description: The fully qualified user ID of the user being banned. - reason: - x-addedInMatrixVersion: "1.1" - type: string - description: The reason the user has been banned. This will be supplied as the - `reason` on the target's updated [`m.room.member`](/client-server-api/#mroommember) event. - required: ["user_id"] + properties: + user_id: + type: string + description: The fully qualified user ID of the user being banned. + reason: + x-addedInMatrixVersion: "1.1" + type: string + description: The reason the user has been banned. This will be supplied as the + `reason` on the target's updated + [`m.room.member`](/client-server-api/#mroommember) event. + required: + - user_id + required: true responses: - 200: + "200": description: The user has been kicked and banned from the room. - examples: - application/json: { - } - schema: - type: object - 403: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "403": description: |- You do not have permission to ban the user from the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are: - The banner is not currently in the room. - The banner's power level is insufficient to ban users from the room. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "You do not have a high enough power level to ban from this room." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You do not have a high enough power level to ban from this room." + } tags: - Room membership "/rooms/{roomId}/unban": @@ -101,50 +99,74 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId - description: The room identifier (not alias) from which the user should be unbanned. - required: true - x-example: "!e42d8c:matrix.org" - - in: body - name: body + description: The room identifier (not alias) from which the user should be + unbanned. required: true + example: "!e42d8c:matrix.org" schema: - type: object - example: { - "user_id": "@cheeky_monkey:matrix.org", - "reason": "They've been banned long enough" - } - properties: - user_id: - type: string - description: The fully qualified user ID of the user being unbanned. - reason: - x-addedInMatrixVersion: "1.1" - type: string - description: |- - Optional reason to be included as the `reason` on the subsequent - membership event. - required: ["user_id"] + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { + "user_id": "@cheeky_monkey:matrix.org", + "reason": "They've been banned long enough" + } + properties: + user_id: + type: string + description: The fully qualified user ID of the user being unbanned. + reason: + x-addedInMatrixVersion: "1.1" + type: string + description: |- + Optional reason to be included as the `reason` on the subsequent + membership event. + required: + - user_id + required: true responses: - 200: + "200": description: The user has been unbanned from the room. - examples: - application/json: { - } - schema: - type: object - 403: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "403": description: |- You do not have permission to unban the user from the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are: - The unbanner's power level is insufficient to unban users from the room. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "You do not have a high enough power level to unban from this room." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You do not have a high enough power level to unban from this room." + } tags: - Room membership +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 diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml index d31d01d7d..96fdfb56c 100644 --- a/data/api/client-server/capabilities.yaml +++ b/data/api/client-server/capabilities.yaml @@ -11,21 +11,12 @@ # 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 Capabilities API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Capabilities API + version: 1.0.0 paths: - "/capabilities": + /capabilities: get: summary: Gets information about the server's capabilities. description: |- @@ -34,79 +25,99 @@ paths: operationId: getCapabilities security: - accessToken: [] - parameters: [] responses: - 200: - description: - The capabilities of the server. - examples: - application/json: { - "capabilities": { - "m.change_password": { - "enabled": false - }, - "m.room_versions": { - "default": "1", - "available": { - "1": "stable", - "2": "stable", - "3": "unstable", - "test-version": "unstable" - } - }, - "com.example.custom.ratelimit": { - "max_requests_per_hour": 600 - } - } - } - schema: - type: object - required: ["capabilities"] - properties: - capabilities: + "200": + description: The capabilities of the server. + content: + application/json: + schema: type: object - title: Capabilities - description: |- - The custom capabilities the server supports, using the - Java package naming convention. - additionalProperties: - type: object + required: + - capabilities properties: - "m.change_password": + capabilities: type: object + title: Capabilities description: |- - Capability to indicate if the user can change their password. - title: ChangePasswordCapability - properties: - enabled: - type: boolean - description: |- - True if the user can change their password, false otherwise. - example: false - required: ['enabled'] - "m.room_versions": - type: object - description: The room versions the server supports. - title: RoomVersionsCapability + The custom capabilities the server supports, using the + Java package naming convention. + additionalProperties: + type: object properties: - default: - type: string - description: |- - The default room version the server is using for new rooms. - example: "1" - available: + m.change_password: type: object - description: |- - A detailed description of the room versions the server supports. - additionalProperties: - type: string - title: RoomVersionStability - enum: [stable, unstable] - description: The stability of the room version. - required: ['default', 'available'] - 429: + description: Capability to indicate if the user can change their password. + title: ChangePasswordCapability + properties: + enabled: + type: boolean + description: True if the user can change their password, false otherwise. + example: false + required: + - enabled + m.room_versions: + type: object + description: The room versions the server supports. + title: RoomVersionsCapability + properties: + default: + type: string + description: The default room version the server is using for new rooms. + example: "1" + available: + type: object + description: A detailed description of the room versions the server supports. + additionalProperties: + type: string + title: RoomVersionStability + enum: + - stable + - unstable + description: The stability of the room version. + required: + - default + - available + examples: + response: + value: { + "capabilities": { + "m.change_password": { + "enabled": false + }, + "m.room_versions": { + "default": "1", + "available": { + "1": "stable", + "2": "stable", + "3": "unstable", + "test-version": "unstable" + } + }, + "com.example.custom.ratelimit": { + "max_requests_per_hour": 600 + } + } + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Capabilities +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 diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml index 328ae1c40..c7e202e91 100644 --- a/data/api/client-server/content-repo.yaml +++ b/data/api/client-server/content-repo.yaml @@ -12,93 +12,99 @@ # 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 Content Repository API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix -consumes: - - application/json - - "*/*" -produces: - - application/json - - "*/*" -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Content Repository API + version: 1.0.0 paths: - "/media/v3/upload": + /media/v3/upload: post: summary: Upload some content to the content repository. operationId: uploadContent - produces: ["application/json"] security: - accessToken: [] parameters: - in: header name: Content-Type - type: string description: The content type of the file being uploaded - x-example: "application/pdf" + example: application/pdf + schema: + type: string - in: query - type: string - x-example: "War and Peace.pdf" name: filename description: The name of the file being uploaded - - in: body - name: "content" - description: The content to be uploaded. - required: true - x-example: "" # so the spec shows "" without quotes. + example: War and Peace.pdf schema: type: string - example: "" - format: byte + requestBody: + content: + application/json: + schema: + type: string + example: + format: byte + "*/*": + schema: + type: string + example: + format: byte + description: The content to be uploaded. + required: true responses: - 200: - description: The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) for the uploaded content. - schema: - type: object - required: ["content_uri"] - properties: - content_uri: - type: string - format: uri - description: "The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) to the uploaded content." - examples: - application/json: { - "content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw" - } - 403: + "200": + description: The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) for + the uploaded content. + content: + application/json: + schema: + type: object + required: + - content_uri + properties: + content_uri: + type: string + format: uri + description: The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) to + the uploaded content. + examples: + response: + value: { + "content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw" + } + "403": description: |- The user does not have permission to upload the content. Some reasons for this error include: - The server does not permit the file type. - The user has reached a quota for uploaded content. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "Cannot upload this content" - } - schema: - "$ref": "definitions/errors/error.yaml" - 413: - description: |- - The uploaded content is too large for the server. - examples: - application/json: { - "errcode": "M_TOO_LARGE", - "error": "Cannot upload files larger than 100mb" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "Cannot upload this content" + } + "413": + description: The uploaded content is too large for the server. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TOO_LARGE", + "error": "Cannot upload files larger than 100mb" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Media "/media/v3/upload/{serverName}/{mediaId}": @@ -111,46 +117,61 @@ paths: x-addedInMatrixVersion: "1.7" parameters: - in: path - type: string name: serverName - x-example: matrix.org required: true description: | The server name from the `mxc://` URI returned by `POST /_matrix/media/v1/create` (the authoritory component). + example: matrix.org + schema: + type: string - in: path - type: string name: mediaId - x-example: ascERGshawAWawugaAcauga required: true description: | The media ID from the `mxc://` URI returned by `POST /_matrix/media/v1/create` (the path component). + example: ascERGshawAWawugaAcauga + schema: + type: string - in: header name: Content-Type - type: string description: The content type of the file being uploaded - x-example: "application/pdf" + example: application/pdf + schema: + type: string - in: query - type: string - x-example: "War and Peace.pdf" name: filename description: The name of the file being uploaded - - in: body - name: "content" - description: The content to be uploaded. - required: true - x-example: "" # so the spec shows "" without quotes. + example: War and Peace.pdf schema: type: string - example: "" - format: byte + requestBody: + content: + application/json: + schema: + type: string + example: + format: byte + "*/*": + schema: + type: string + example: + format: byte + description: The content to be uploaded. + required: true responses: - 200: + "200": description: The upload was successful. - schema: - type: object - examples: - application/json: {} - 403: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "*/*": + schema: + type: object + "403": description: |- The user does not have permission to upload the content. Some reasons for this error include: @@ -161,42 +182,64 @@ paths: A [standard error response](/client-server-api/#standard-error-response) will be returned with the `errcode` `M_FORBIDDEN`. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "Cannot upload this content" - } - schema: - "$ref": "definitions/errors/error.yaml" - 409: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "Cannot upload this content" + } + "*/*": + schema: + $ref: definitions/errors/error.yaml + "409": description: |- The endpoint was called with a media ID that already has content. A [standard error response](/client-server-api/#standard-error-response) will be returned with the `errcode` `M_CANNOT_OVERWRITE_MEDIA`. - examples: - application/json: { - "errcode": "M_CANNOT_OVERWRITE_MEDIA", - "error": "Media already uploaded" - } - schema: - "$ref": "definitions/errors/error.yaml" - 413: - description: |- - The uploaded content is too large for the server. - examples: - application/json: { - "errcode": "M_TOO_LARGE", - "error": "Cannot upload files larger than 100mb" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_CANNOT_OVERWRITE_MEDIA", + "error": "Media already uploaded" + } + "*/*": + schema: + $ref: definitions/errors/error.yaml + "413": + description: The uploaded content is too large for the server. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TOO_LARGE", + "error": "Cannot upload files larger than 100mb" + } + "*/*": + schema: + $ref: definitions/errors/error.yaml + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml + "*/*": + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Media - "/media/v1/create": + /media/v1/create: post: summary: Create a new `mxc://` URI without uploading the content. description: |- @@ -220,87 +263,89 @@ paths: server should respond with an HTTP 429 error with an errcode of `M_LIMIT_EXCEEDED`. operationId: createContent - consumes: ["application/json"] - produces: ["application/json"] x-addedInMatrixVersion: "1.7" security: - accessToken: [] - # empty json object - parameters: [] responses: - 200: - description: The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) for the uploaded content. - schema: - type: object - required: ["content_uri"] - properties: - content_uri: - type: string - format: uri - description: |- - The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) at - which the content will be available, once it is uploaded. - example: "mxc://example.com/AQwafuaFswefuhsfAFAgsw" - unused_expires_at: - type: integer - format: int64 - description: |- - The timestamp (in milliseconds since the unix epoch) when the - generated media id will expire, if media is not uploaded. - example: 1647257217083 - 403: - description: |- - The user does not have permission to upload the content. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "Cannot upload this content" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + "200": + description: The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) for + the uploaded content. + content: + application/json: + schema: + type: object + required: + - content_uri + properties: + content_uri: + type: string + format: uri + description: |- + The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) at + which the content will be available, once it is uploaded. + example: mxc://example.com/AQwafuaFswefuhsfAFAgsw + unused_expires_at: + type: integer + format: int64 + description: |- + The timestamp (in milliseconds since the unix epoch) when the + generated media id will expire, if media is not uploaded. + example: 1647257217083 + "403": + description: The user does not have permission to upload the content. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "Cannot upload this content" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Media "/media/v3/download/{serverName}/{mediaId}": get: - summary: "Download content from the content repository." + summary: Download content from the content repository. operationId: getContent - 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) + example: matrix.org + schema: + type: string - in: path - type: string name: mediaId - x-example: ascERGshawAWawugaAcauga required: true description: | The media ID from the `mxc://` URI (the path component) + example: ascERGshawAWawugaAcauga + schema: + type: string - in: query - type: boolean name: allow_remote - x-example: false required: false - default: true description: | Indicates to the server that it should not attempt to fetch the media if it is deemed remote. This is to prevent routing loops where the server contacts itself. Defaults to true if not provided. + example: false + schema: + type: boolean + default: true - in: query - type: integer - format: int64 name: timeout_ms - x-example: 5000 x-addedInMatrixVersion: "1.7" - default: 20000 description: | The maximum number of milliseconds that the client is willing to wait to start receiving data, in the case that the content has not @@ -308,46 +353,63 @@ paths: content repository can and should impose a maximum value for this parameter. The content repository may also choose to respond before the timeout. + example: 5000 + schema: + type: integer + format: int64 + default: 20000 responses: - 200: - description: "The content that was previously uploaded." + "200": + description: The content that was previously uploaded. headers: Content-Type: - description: "The content type of the file that was previously uploaded." - type: "string" + description: The content type of the file that was previously uploaded. + schema: + type: string Content-Disposition: - description: |- - The name of the file that was previously uploaded, if set. - type: "string" - schema: - type: file - # This is a workaround for us not being able to say the response is required. - description: "**Required.** The bytes for the uploaded file." - 429: + description: The name of the file that was previously uploaded, if set. + schema: + type: string + content: + "*/*": + schema: + type: string + description: "**Required.** The bytes for the uploaded file." + format: binary + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" - 502: - description: |- - The content is too large for the server to serve. - examples: - application/json: { - "errcode": "M_TOO_LARGE", - "error": "Content is too large to serve" - } - schema: - "$ref": "definitions/errors/error.yaml" - 504: + content: + "*/*": + schema: + $ref: definitions/errors/rate_limited.yaml + "502": + description: The content is too large for the server to serve. + content: + "*/*": + schema: + $ref: definitions/errors/error.yaml + application/json: + examples: + response: + value: { + "errcode": "M_TOO_LARGE", + "error": "Content is too large to serve" + } + "504": description: |- The content is not yet available. A [standard error response](/client-server-api/#standard-error-response) will be returned with the `errcode` `M_NOT_YET_UPLOADED`. - examples: - application/json: { - "errcode": "M_NOT_YET_UPLOADED", - "error": "Content has not yet been uploaded" - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + "*/*": + schema: + $ref: definitions/errors/error.yaml + application/json: + examples: + response: + value: { + "errcode": "M_NOT_YET_UPLOADED", + "error": "Content has not yet been uploaded" + } tags: - Media "/media/v3/download/{serverName}/{mediaId}/{fileName}": @@ -358,45 +420,44 @@ paths: the previous endpoint) but replace the target file name with the one provided by the caller. operationId: getContentOverrideName - 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) + example: matrix.org + schema: + type: string - in: path - type: string name: mediaId - x-example: ascERGshawAWawugaAcauga required: true description: | The media ID from the `mxc://` URI (the path component) + example: ascERGshawAWawugaAcauga + schema: + type: string - in: path - type: string name: fileName - x-example: filename.jpg required: true description: A filename to give in the `Content-Disposition` header. + example: filename.jpg + schema: + type: string - in: query - type: boolean name: allow_remote - x-example: false required: false - default: true description: | Indicates to the server that it should not attempt to fetch the media if it is deemed remote. This is to prevent routing loops where the server contacts itself. Defaults to true if not provided. + example: false + schema: + type: boolean + default: true - in: query - type: integer - format: int64 name: timeout_ms - x-example: 5000 x-addedInMatrixVersion: "1.7" - default: 20000 description: | The maximum number of milliseconds that the client is willing to wait to start receiving data, in the case that the content has not @@ -404,47 +465,65 @@ paths: content repository can and should impose a maximum value for this parameter. The content repository may also choose to respond before the timeout. + example: 5000 + schema: + type: integer + format: int64 + default: 20000 responses: - 200: - description: "The content that was previously uploaded." + "200": + description: The content that was previously uploaded. headers: Content-Type: - description: "The content type of the file that was previously uploaded." - type: "string" + description: The content type of the file that was previously uploaded. + schema: + type: string Content-Disposition: description: |- The `fileName` requested or the name of the file that was previously uploaded, if set. - type: "string" - schema: - type: file - # This is a workaround for us not being able to say the response is required. - description: "**Required.** The bytes for the uploaded file." - 429: + schema: + type: string + content: + "*/*": + schema: + type: string + description: "**Required.** The bytes for the uploaded file." + format: binary + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" - 502: - description: |- - The content is too large for the server to serve. - examples: - application/json: { - "errcode": "M_TOO_LARGE", - "error": "Content is too large to serve" - } - schema: - "$ref": "definitions/errors/error.yaml" - 504: + content: + "*/*": + schema: + $ref: definitions/errors/rate_limited.yaml + "502": + description: The content is too large for the server to serve. + content: + "*/*": + schema: + $ref: definitions/errors/error.yaml + application/json: + examples: + response: + value: { + "errcode": "M_TOO_LARGE", + "error": "Content is too large to serve" + } + "504": description: |- The content is not yet available. A [standard error response](/client-server-api/#standard-error-response) will be returned with the `errcode` `M_NOT_YET_UPLOADED`. - examples: - application/json: { - "errcode": "M_NOT_YET_UPLOADED", - "error": "Content has not yet been uploaded" - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + "*/*": + schema: + $ref: definitions/errors/error.yaml + application/json: + examples: + response: + value: { + "errcode": "M_NOT_YET_UPLOADED", + "error": "Content has not yet been uploaded" + } tags: - Media "/media/v3/thumbnail/{serverName}/{mediaId}": @@ -454,63 +533,66 @@ paths: Download a thumbnail of content from the content repository. See the [Thumbnails](/client-server-api/#thumbnails) section for more information. operationId: getContentThumbnail - produces: ["image/jpeg", "image/png"] parameters: - in: path - type: string name: serverName required: true - x-example: example.org description: | The server name from the `mxc://` URI (the authoritory component) + example: example.org + schema: + type: string - in: path - type: string name: mediaId - x-example: ascERGshawAWawugaAcauga required: true description: | The media ID from the `mxc://` URI (the path component) + example: ascERGshawAWawugaAcauga + schema: + type: string - in: query - type: integer - x-example: 64 name: width required: true description: |- The *desired* width of the thumbnail. The actual thumbnail may be larger than the size specified. + example: 64 + schema: + type: integer - in: query - type: integer - x-example: 64 name: height required: true description: |- The *desired* height of the thumbnail. The actual thumbnail may be larger than the size specified. + example: 64 + schema: + type: integer - in: query - type: string - enum: ["crop", "scale"] name: method - x-example: "scale" description: |- The desired resizing method. See the [Thumbnails](/client-server-api/#thumbnails) section for more information. + example: scale + schema: + type: string + enum: + - crop + - scale - in: query - type: boolean name: allow_remote - x-example: false required: false - default: true description: |- Indicates to the server that it should not attempt to fetch the media if it is deemed remote. This is to prevent routing loops where the server contacts itself. Defaults to true if not provided. + example: false + schema: + type: boolean + default: true - in: query - type: integer - format: int64 name: timeout_ms - x-example: 5000 x-addedInMatrixVersion: "1.7" - default: 20000 description: | The maximum number of milliseconds that the client is willing to wait to start receiving data, in the case that the content has not @@ -518,70 +600,116 @@ paths: content repository can and should impose a maximum value for this parameter. The content repository may also choose to respond before the timeout. + example: 5000 + schema: + type: integer + format: int64 + default: 20000 responses: - 200: - description: "A thumbnail of the requested content." + "200": + description: A thumbnail of the requested content. headers: Content-Type: - description: "The content type of the thumbnail." - type: "string" - enum: ["image/jpeg", "image/png"] - schema: - type: file - # This is a workaround for us not being able to say the response is required. - description: "**Required.** The bytes for the thumbnail." - 400: + description: The content type of the thumbnail. + schema: + type: string + enum: + - image/jpeg + - image/png + content: + image/jpeg: + schema: + type: string + description: "**Required.** The bytes for the thumbnail." + format: binary + image/png: + schema: + type: string + description: "**Required.** The bytes for the thumbnail." + format: binary + "400": description: |- The request does not make sense to the server, or the server cannot thumbnail the content. For example, the client requested non-integer dimensions or asked for negatively-sized images. - examples: - application/json: { - "errcode": "M_UNKNOWN", - "error": "Cannot generate thumbnails for the requested content" - } - schema: - "$ref": "definitions/errors/error.yaml" - 413: - description: |- - The local content is too large for the server to thumbnail. - examples: - application/json: { - "errcode": "M_TOO_LARGE", - "error": "Content is too large to thumbnail" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + image/jpeg: + schema: + $ref: definitions/errors/error.yaml + image/png: + schema: + $ref: definitions/errors/error.yaml + application/json: + examples: + response: + value: { + "errcode": "M_UNKNOWN", + "error": "Cannot generate thumbnails for the requested content" + } + "413": + description: The local content is too large for the server to thumbnail. + content: + image/jpeg: + schema: + $ref: definitions/errors/error.yaml + image/png: + schema: + $ref: definitions/errors/error.yaml + application/json: + examples: + response: + value: { + "errcode": "M_TOO_LARGE", + "error": "Content is too large to thumbnail" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" - 502: - description: |- - The remote content is too large for the server to thumbnail. - examples: - application/json: { - "errcode": "M_TOO_LARGE", - "error": "Content is too large to thumbnail" - } - schema: - "$ref": "definitions/errors/error.yaml" - 504: + content: + image/jpeg: + schema: + $ref: definitions/errors/rate_limited.yaml + image/png: + schema: + $ref: definitions/errors/rate_limited.yaml + "502": + description: The remote content is too large for the server to thumbnail. + content: + image/jpeg: + schema: + $ref: definitions/errors/error.yaml + image/png: + schema: + $ref: definitions/errors/error.yaml + application/json: + examples: + response: + value: { + "errcode": "M_TOO_LARGE", + "error": "Content is too large to thumbnail" + } + "504": description: |- The content is not yet available. A [standard error response](/client-server-api/#standard-error-response) will be returned with the `errcode` `M_NOT_YET_UPLOADED`. - examples: - application/json: { - "errcode": "M_NOT_YET_UPLOADED", - "error": "Content has not yet been uploaded" - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + image/jpeg: + schema: + $ref: definitions/errors/error.yaml + image/png: + schema: + $ref: definitions/errors/error.yaml + application/json: + examples: + response: + value: { + "errcode": "M_NOT_YET_UPLOADED", + "error": "Content has not yet been uploaded" + } tags: - Media - "/media/v3/preview_url": + /media/v3/preview_url: get: - summary: "Get information about a URL for a client" + summary: Get information about a URL for a client description: |- Get information about a URL for the client. Typically this is called when a client sees a URL in a message and wants to render a preview for the user. @@ -591,64 +719,68 @@ paths: rooms. Encrypted rooms often contain more sensitive information the users do not want to share with the homeserver, and this can mean that the URLs being shared should also not be shared with the homeserver. - operationId: getUrlPreview - produces: ["application/json"] security: - accessToken: [] parameters: - in: query - type: string - format: uri - x-example: "https://matrix.org" name: url - description: "The URL to get a preview of." + description: The URL to get a preview of. required: true + example: https://matrix.org + schema: + type: string + format: uri - in: query - type: integer - format: int64 - x-example: 1510610716656 name: ts description: |- The preferred point in time to return a preview for. The server may return a newer version if it does not have the requested version available. + example: 1510610716656 + schema: + type: integer + format: int64 responses: - 200: + "200": description: |- The OpenGraph data for the URL, which may be empty. Some values are replaced with matrix equivalents if they are provided in the response. The differences from the OpenGraph protocol are described here. - schema: - type: object - properties: - "matrix:image:size": - type: integer - format: int64 - description: |- - The byte-size of the image. Omitted if there is no image attached. - "og:image": - type: string - format: uri - description: |- - An [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) to the image. Omitted if there is no image. - examples: - application/json: { - "og:title": "Matrix Blog Post", - "og:description": "This is a really cool blog post from matrix.org", - "og:image": "mxc://example.com/ascERGshawAWawugaAcauga", - "og:image:type": "image/png", - "og:image:height": 48, - "og:image:width": 48, - "matrix:image:size": 102400 - } - 429: + content: + application/json: + schema: + type: object + properties: + matrix:image:size: + type: integer + format: int64 + description: The byte-size of the image. Omitted if there is no image attached. + og:image: + type: string + format: uri + description: An [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) to + the image. Omitted if there is no image. + examples: + response: + value: { + "og:title": "Matrix Blog Post", + "og:description": "This is a really cool blog post from matrix.org", + "og:image": "mxc://example.com/ascERGshawAWawugaAcauga", + "og:image:type": "image/png", + "og:image:height": 48, + "og:image:width": 48, + "matrix:image:size": 102400 + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Media - "/media/v3/config": + /media/v3/config: get: summary: Get the configuration for the content repository. description: |- @@ -663,30 +795,48 @@ paths: repository APIs, for example, proxies may enforce a lower upload size limit than is advertised by the server on this endpoint. operationId: getConfig - produces: ["application/json"] security: - accessToken: [] responses: - 200: + "200": description: The public content repository configuration for the matrix server. - schema: - type: object - properties: - m.upload.size: - type: integer - format: int64 - description: |- - The maximum size an upload can be in bytes. - Clients SHOULD use this as a guide when uploading content. - If not listed or null, the size limit should be treated as unknown. - examples: - application/json: { - "m.upload.size": 50000000 - } - 429: + content: + application/json: + schema: + type: object + properties: + m.upload.size: + type: integer + format: int64 + description: |- + The maximum size an upload can be in bytes. + Clients SHOULD use this as a guide when uploading content. + If not listed or null, the size limit should be treated as unknown. + examples: + response: + value: { + "m.upload.size": 50000000 + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/error.yaml" - + content: + application/json: + schema: + $ref: definitions/errors/error.yaml tags: - Media +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/create_room.yaml b/data/api/client-server/create_room.yaml index a39cc4f57..2188a370e 100644 --- a/data/api/client-server/create_room.yaml +++ b/data/api/client-server/create_room.yaml @@ -12,23 +12,12 @@ # 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 Room Creation 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 Room Creation API + version: 1.0.0 paths: - "/createRoom": + /createRoom: post: summary: Create a new room description: |- @@ -76,177 +65,192 @@ paths: operationId: createRoom security: - accessToken: [] - parameters: - - in: body - name: body - description: The desired room configuration. - required: true - schema: - type: object - example: { - "preset": "public_chat", - "room_alias_name": "thepub", - "name": "The Grand Duke Pub", - "topic": "All about happy hour", - "creation_content": { + requestBody: + content: + application/json: + schema: + type: object + example: { + "preset": "public_chat", + "room_alias_name": "thepub", + "name": "The Grand Duke Pub", + "topic": "All about happy hour", + "creation_content": { "m.federate": false + } } - } - properties: - visibility: - type: string - enum: ["public", "private"] - description: |- - A `public` visibility indicates that the room will be shown - in the published room list. A `private` visibility will hide - the room from the published room list. Rooms default to - `private` visibility if this key is not included. NB: This - should not be confused with `join_rules` which also uses the - word `public`. - room_alias_name: - type: string - description: |- - The desired room alias **local part**. If this is included, a - room alias will be created and mapped to the newly created - room. The alias will belong on the *same* homeserver which - created the room. For example, if this was set to "foo" and - sent to the homeserver "example.com" the complete room alias - would be `#foo:example.com`. + properties: + visibility: + type: string + enum: + - public + - private + description: |- + A `public` visibility indicates that the room will be shown + in the published room list. A `private` visibility will hide + the room from the published room list. Rooms default to + `private` visibility if this key is not included. NB: This + should not be confused with `join_rules` which also uses the + word `public`. + room_alias_name: + type: string + description: |- + The desired room alias **local part**. If this is included, a + room alias will be created and mapped to the newly created + room. The alias will belong on the *same* homeserver which + created the room. For example, if this was set to "foo" and + sent to the homeserver "example.com" the complete room alias + would be `#foo:example.com`. - The complete room alias will become the canonical alias for - the room and an `m.room.canonical_alias` event will be sent - into the room. - name: - type: string - description: |- - If this is included, an `m.room.name` event will be sent - into the room to indicate the name of the room. See Room - Events for more information on `m.room.name`. - topic: - type: string - description: |- - If this is included, an `m.room.topic` event will be sent - into the room to indicate the topic for the room. See Room - Events for more information on `m.room.topic`. - invite: - type: array - description: |- - A list of user IDs to invite to the room. This will tell the - server to invite everyone in the list to the newly created room. - items: + The complete room alias will become the canonical alias for + the room and an `m.room.canonical_alias` event will be sent + into the room. + name: + type: string + description: |- + If this is included, an `m.room.name` event will be sent + into the room to indicate the name of the room. See Room + Events for more information on `m.room.name`. + topic: type: string - invite_3pid: - type: array - description: |- - A list of objects representing third-party IDs to invite into - the room. - items: + description: |- + If this is included, an `m.room.topic` event will be sent + into the room to indicate the topic for the room. See Room + Events for more information on `m.room.topic`. + invite: + type: array + description: |- + A list of user IDs to invite to the room. This will tell the + server to invite everyone in the list to the newly created room. + items: + type: string + invite_3pid: + type: array + description: |- + A list of objects representing third-party IDs to invite into + the room. + items: + type: object + title: Invite3pid + properties: + id_server: + type: string + description: The hostname+port of the identity server which should be used for + third-party identifier lookups. + id_access_token: + type: string + description: |- + An access token previously registered with the identity server. Servers + can treat this as optional to distinguish between r0.5-compatible clients + and this specification version. + medium: + type: string + description: |- + The kind of address being passed in the address field, for example `email` + (see [the list of recognised values](/appendices/#3pid-types)). + address: + type: string + description: The invitee's third-party identifier. + required: + - id_server + - id_access_token + - medium + - address + room_version: + type: string + description: |- + The room version to set for the room. If not provided, the homeserver is + to use its configured default. If provided, the homeserver will return a + 400 error with the errcode `M_UNSUPPORTED_ROOM_VERSION` if it does not + support the room version. + example: "1" + creation_content: + title: CreationContent type: object - title: Invite3pid - properties: - id_server: - type: string - description: The hostname+port of the identity server which should be used for third-party identifier lookups. - id_access_token: - type: string - description: |- - An access token previously registered with the identity server. Servers - can treat this as optional to distinguish between r0.5-compatible clients - and this specification version. - medium: - type: string - description: |- - The kind of address being passed in the address field, for example `email` - (see [the list of recognised values](/appendices/#3pid-types)). - address: - type: string - description: The invitee's third-party identifier. - required: ["id_server", "id_access_token", "medium", "address"] - room_version: - type: string - description: |- - The room version to set for the room. If not provided, the homeserver is - to use its configured default. If provided, the homeserver will return a - 400 error with the errcode `M_UNSUPPORTED_ROOM_VERSION` if it does not - support the room version. - example: "1" - creation_content: - title: CreationContent - type: object - description: |- - Extra keys, such as `m.federate`, to be added to the content - of the [`m.room.create`](/client-server-api/#mroomcreate) event. The server will overwrite the following - keys: `creator`, `room_version`. Future versions of the specification - may allow the server to overwrite other keys. - initial_state: - type: array - description: |- - A list of state events to set in the new room. This allows - the user to override the default state events set in the new - room. The expected format of the state events are an object - with type, state_key and content keys set. + description: |- + Extra keys, such as `m.federate`, to be added to the content + of the [`m.room.create`](/client-server-api/#mroomcreate) event. The server will overwrite the following + keys: `creator`, `room_version`. Future versions of the specification + may allow the server to overwrite other keys. + initial_state: + type: array + description: |- + A list of state events to set in the new room. This allows + the user to override the default state events set in the new + room. The expected format of the state events are an object + with type, state_key and content keys set. - Takes precedence over events set by `preset`, but gets - overridden by `name` and `topic` keys. - items: - type: object - title: StateEvent - properties: - type: - type: string - description: The type of event to send. - state_key: - type: string - description: The state_key of the state event. Defaults to an empty string. - content: - type: object - description: The content of the event. - required: ["type", "content"] - preset: - type: string - enum: ["private_chat", "public_chat", "trusted_private_chat"] - description: |- - Convenience parameter for setting various default state events - based on a preset. + Takes precedence over events set by `preset`, but gets + overridden by `name` and `topic` keys. + items: + type: object + title: StateEvent + properties: + type: + type: string + description: The type of event to send. + state_key: + type: string + description: The state_key of the state event. Defaults to an empty string. + content: + type: object + description: The content of the event. + required: + - type + - content + preset: + type: string + enum: + - private_chat + - public_chat + - trusted_private_chat + description: |- + Convenience parameter for setting various default state events + based on a preset. - If unspecified, the server should use the `visibility` to determine - which preset to use. A visbility of `public` equates to a preset of - `public_chat` and `private` visibility equates to a preset of - `private_chat`. - is_direct: - type: boolean - description: |- - This flag makes the server set the `is_direct` flag on the - `m.room.member` events sent to the users in `invite` and - `invite_3pid`. See [Direct Messaging](/client-server-api/#direct-messaging) for more information. - power_level_content_override: - title: Power Level Event Content - type: object - description: |- - The power level content to override in the default power level - event. This object is applied on top of the generated - [`m.room.power_levels`](/client-server-api/#mroompower_levels) - event content prior to it being sent to the room. Defaults to - overriding nothing. + If unspecified, the server should use the `visibility` to determine + which preset to use. A visbility of `public` equates to a preset of + `public_chat` and `private` visibility equates to a preset of + `private_chat`. + is_direct: + type: boolean + description: |- + This flag makes the server set the `is_direct` flag on the + `m.room.member` events sent to the users in `invite` and + `invite_3pid`. See [Direct Messaging](/client-server-api/#direct-messaging) for more information. + power_level_content_override: + title: Power Level Event Content + type: object + description: |- + The power level content to override in the default power level + event. This object is applied on top of the generated + [`m.room.power_levels`](/client-server-api/#mroompower_levels) + event content prior to it being sent to the room. Defaults to + overriding nothing. + description: The desired room configuration. + required: true responses: - 200: + "200": description: Information about the newly created room. - schema: - type: object - description: Information about the newly created room. - properties: - room_id: - type: string - description: |- - The created room's ID. - required: ['room_id'] - examples: - application/json: { - "room_id": "!sefiuhWgwghwWgh:example.com" - } - 400: + content: + application/json: + schema: + type: object + description: Information about the newly created room. + properties: + room_id: + type: string + description: The created room's ID. + required: + - room_id + examples: + response: + value: { + "room_id": "!sefiuhWgwghwWgh:example.com" + } + "400": description: |- - + The request is invalid. A meaningful `errcode` and description error text will be returned. Example reasons for rejection include: @@ -266,7 +270,24 @@ paths: of a homeserver which does not support the requested room version. The `errcode` will be `M_UNSUPPORTED_ROOM_VERSION` in these cases. - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml tags: - Room creation +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 diff --git a/data/api/client-server/cross_signing.yaml b/data/api/client-server/cross_signing.yaml index 817aeca90..2f038e803 100644 --- a/data/api/client-server/cross_signing.yaml +++ b/data/api/client-server/cross_signing.yaml @@ -11,23 +11,12 @@ # 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 Cross Signing 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 Cross Signing API + version: 1.0.0 paths: - "/keys/device_signing/upload": + /keys/device_signing/upload: post: x-addedInMatrixVersion: "1.1" summary: Upload cross-signing keys. @@ -38,87 +27,93 @@ paths: operationId: uploadCrossSigningKeys security: - accessToken: [] - parameters: - - in: body - name: keys - description: |- - The keys to be published. - required: true - schema: - type: object - properties: - master_key: - description: |- - Optional. The user\'s master key. - allOf: - - $ref: definitions/cross_signing_key.yaml - self_signing_key: - description: |- - Optional. The user\'s self-signing key. Must be signed by - the accompanying master key, or by the user\'s most recently - uploaded master key if no master key is included in the - request. - allOf: - - $ref: definitions/cross_signing_key.yaml - user_signing_key: - description: |- - Optional. The user\'s user-signing key. Must be signed by - the accompanying master key, or by the user\'s most recently - uploaded master key if no master key is included in the - request. - allOf: - - $ref: definitions/cross_signing_key.yaml - auth: - description: |- - Additional authentication information for the - user-interactive authentication API. - allOf: - - $ref: "definitions/auth_data.yaml" - example: { - "auth": { - "type": "example.type.foo", - "session": "xxxxx", - "example_credential": "verypoorsharedsecret" - }, - "master_key": { - "user_id": "@alice:example.com", - "usage": ["master"], - "keys": { - "ed25519:base64+master+public+key": "base64+master+public+key", - } - }, - "self_signing_key": { - "user_id": "@alice:example.com", - "usage": ["self_signing"], - "keys": { - "ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key", + requestBody: + content: + application/json: + schema: + type: object + properties: + master_key: + description: Optional. The user\'s master key. + allOf: + - $ref: definitions/cross_signing_key.yaml + self_signing_key: + description: |- + Optional. The user\'s self-signing key. Must be signed by + the accompanying master key, or by the user\'s most recently + uploaded master key if no master key is included in the + request. + allOf: + - $ref: definitions/cross_signing_key.yaml + user_signing_key: + description: |- + Optional. The user\'s user-signing key. Must be signed by + the accompanying master key, or by the user\'s most recently + uploaded master key if no master key is included in the + request. + allOf: + - $ref: definitions/cross_signing_key.yaml + auth: + description: |- + Additional authentication information for the + user-interactive authentication API. + allOf: + - $ref: definitions/auth_data.yaml + example: { + "auth": { + "type": "example.type.foo", + "session": "xxxxx", + "example_credential": "verypoorsharedsecret" }, - "signatures": { - "@alice:example.com": { - "ed25519:base64+master+public+key": "signature+of+self+signing+key" + "master_key": { + "user_id": "@alice:example.com", + "usage": [ + "master" + ], + "keys": { + "ed25519:base64+master+public+key": "base64+master+public+key" + } + }, + "self_signing_key": { + "user_id": "@alice:example.com", + "usage": [ + "self_signing" + ], + "keys": { + "ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key" + }, + "signatures": { + "@alice:example.com": { + "ed25519:base64+master+public+key": "signature+of+self+signing+key" + } } - } - }, - "user_signing_key": { - "user_id": "@alice:example.com", - "usage": ["user_signing"], - "keys": { - "ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key", }, - "signatures": { - "@alice:example.com": { - "ed25519:base64+master+public+key": "signature+of+user+signing+key" + "user_signing_key": { + "user_id": "@alice:example.com", + "usage": [ + "user_signing" + ], + "keys": { + "ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key" + }, + "signatures": { + "@alice:example.com": { + "ed25519:base64+master+public+key": "signature+of+user+signing+key" + } } } } - } + description: The keys to be published. + required: true responses: - 200: + "200": description: The provided keys were successfully uploaded. - schema: - type: object - example: {} - 400: + content: + application/json: + schema: + type: object + example: {} + "400": description: |- The input was invalid in some way. This can include one of the following error codes: @@ -126,25 +121,29 @@ paths: * `M_INVALID_SIGNATURE`: For example, the self-signing or user-signing key had an incorrect signature. * `M_MISSING_PARAM`: No master key is available. - schema: - type: object - example: { - "errcode": "M_INVALID_SIGNATURE", - "error": "Invalid signature" - } - 403: + content: + application/json: + schema: + type: object + example: { + "errcode": "M_INVALID_SIGNATURE", + "error": "Invalid signature" + } + "403": description: |- The public key of one of the keys is the same as one of the user\'s device IDs, or the request is not authorized for any other reason. - schema: - type: object - example: { - "errcode": "M_FORBIDDEN", - "error": "Key ID in use" - } + content: + application/json: + schema: + type: object + example: { + "errcode": "M_FORBIDDEN", + "error": "Key ID in use" + } tags: - End-to-end encryption - "/keys/signatures/upload": + /keys/signatures/upload: post: x-addedInMatrixVersion: "1.1" summary: Upload cross-signing signatures. @@ -158,91 +157,109 @@ paths: operationId: uploadCrossSigningSignatures security: - accessToken: [] - parameters: - - in: body - name: signatures - description: |- - A map from user ID to key ID to signed JSON objects containing the - signatures to be published. - required: true - schema: - type: object - title: Signatures - additionalProperties: + requestBody: + content: + application/json: + schema: type: object + title: Signatures additionalProperties: type: object - example: { - "@alice:example.com": { - "HIJKLMN": { - "user_id": "@alice:example.com", - "device_id": "HIJKLMN", - "algorithms": [ - "m.olm.v1.curve25519-aes-sha256", - "m.megolm.v1.aes-sha" - ], - "keys": { - "curve25519:HIJKLMN": "base64+curve25519+key", - "ed25519:HIJKLMN": "base64+ed25519+key" - }, - "signatures": { - "@alice:example.com": { - "ed25519:base64+self+signing+public+key": "base64+signature+of+HIJKLMN" + additionalProperties: + type: object + example: { + "@alice:example.com": { + "HIJKLMN": { + "user_id": "@alice:example.com", + "device_id": "HIJKLMN", + "algorithms": [ + "m.olm.v1.curve25519-aes-sha256", + "m.megolm.v1.aes-sha" + ], + "keys": { + "curve25519:HIJKLMN": "base64+curve25519+key", + "ed25519:HIJKLMN": "base64+ed25519+key" + }, + "signatures": { + "@alice:example.com": { + "ed25519:base64+self+signing+public+key": "base64+signature+of+HIJKLMN" + } } - } - }, - "base64+master+public+key": { - "user_id": "@alice:example.com", - "usage": ["master"], - "keys": { - "ed25519:base64+master+public+key": "base64+master+public+key" }, - "signatures": { - "@alice:example.com": { - "ed25519:HIJKLMN": "base64+signature+of+master+key" + "base64+master+public+key": { + "user_id": "@alice:example.com", + "usage": [ + "master" + ], + "keys": { + "ed25519:base64+master+public+key": "base64+master+public+key" + }, + "signatures": { + "@alice:example.com": { + "ed25519:HIJKLMN": "base64+signature+of+master+key" + } } } - } - }, - "@bob:example.com": { - "bobs+base64+master+public+key": { - "user_id": "@bob:example.com", - "keys": { - "ed25519:bobs+base64+master+public+key": "bobs+base64+master+public+key" - }, - "usage": ["master"], - "signatures": { - "@alice:example.com": { - "ed25519:base64+user+signing+public+key": "base64+signature+of+bobs+master+key" + }, + "@bob:example.com": { + "bobs+base64+master+public+key": { + "user_id": "@bob:example.com", + "keys": { + "ed25519:bobs+base64+master+public+key": "bobs+base64+master+public+key" + }, + "usage": [ + "master" + ], + "signatures": { + "@alice:example.com": { + "ed25519:base64+user+signing+public+key": "base64+signature+of+bobs+master+key" + } } } } } - } + description: |- + A map from user ID to key ID to signed JSON objects containing the + signatures to be published. + required: true responses: - 200: + "200": description: The provided signatures were processed. - schema: - type: object - properties: - failures: + content: + application/json: + schema: type: object - description: |- - A map from user ID to key ID to an error for any signatures - that failed. If a signature was invalid, the `errcode` will - be set to `M_INVALID_SIGNATURE`. - additionalProperties: - type: object - additionalProperties: + properties: + failures: type: object - title: Error - example: { - "@alice:example.com": { - "HIJKLMN": { - "errcode": "M_INVALID_SIGNATURE", - "error": "Invalid signature" - } - } - } + description: |- + A map from user ID to key ID to an error for any signatures + that failed. If a signature was invalid, the `errcode` will + be set to `M_INVALID_SIGNATURE`. + additionalProperties: + type: object + additionalProperties: + type: object + title: Error + example: + "@alice:example.com": + HIJKLMN: + errcode: M_INVALID_SIGNATURE + error: Invalid signature tags: - End-to-end encryption +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 diff --git a/data/api/client-server/definitions/push_condition.yaml b/data/api/client-server/definitions/push_condition.yaml index 4f2fe4726..8a3a9f32c 100644 --- a/data/api/client-server/definitions/push_condition.yaml +++ b/data/api/client-server/definitions/push_condition.yaml @@ -30,7 +30,7 @@ properties: the power level event the user needs a minimum power level for. Fields must be specified under the `notifications` property in the power level event's `content`. - x-example: content.body + example: content.body pattern: type: string description: |- diff --git a/data/api/client-server/device_management.yaml b/data/api/client-server/device_management.yaml index 84e5ee23a..9ae3f5578 100644 --- a/data/api/client-server/device_management.yaml +++ b/data/api/client-server/device_management.yaml @@ -11,126 +11,124 @@ # 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 device management 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 device management API + version: 1.0.0 paths: - "/devices": + /devices: get: summary: List registered devices for the current user - description: |- - Gets information about all devices for the current user. + description: Gets information about all devices for the current user. operationId: getDevices security: - accessToken: [] responses: - 200: + "200": description: Device information - schema: - type: object - properties: - devices: - type: array - description: A list of all registered devices for this user. - items: - type: object - allOf: - - $ref: "definitions/client_device.yaml" - examples: - application/json: { - "devices": [ - { - "device_id": "QBUAZIFURK", - "display_name": "android", - "last_seen_ip": "1.2.3.4", - "last_seen_ts": 1474491775024 + content: + application/json: + schema: + type: object + properties: + devices: + type: array + description: A list of all registered devices for this user. + items: + type: object + allOf: + - $ref: definitions/client_device.yaml + examples: + response: + value: { + "devices": [ + { + "device_id": "QBUAZIFURK", + "display_name": "android", + "last_seen_ip": "1.2.3.4", + "last_seen_ts": 1474491775024 + } + ] } - ] - } tags: - Device management "/devices/{deviceId}": get: summary: Get a single device - description: |- - Gets information on a single device, by device id. + description: Gets information on a single device, by device id. operationId: getDevice security: - accessToken: [] parameters: - in: path - type: string name: deviceId description: The device to retrieve. required: true - x-example: "QBUAZIFURK" + example: QBUAZIFURK + schema: + type: string responses: - 200: + "200": description: Device information - schema: - type: object - allOf: - - $ref: "definitions/client_device.yaml" - examples: - application/json: { - "device_id": "QBUAZIFURK", - "display_name": "android", - "last_seen_ip": "1.2.3.4", - "last_seen_ts": 1474491775024 - } - 404: + content: + application/json: + schema: + type: object + allOf: + - $ref: definitions/client_device.yaml + examples: + response: + value: { + "device_id": "QBUAZIFURK", + "display_name": "android", + "last_seen_ip": "1.2.3.4", + "last_seen_ts": 1474491775024 + } + "404": description: The current user has no device with the given ID. tags: - Device management put: summary: Update a device - description: |- - Updates the metadata on the given device. + description: Updates the metadata on the given device. operationId: updateDevice security: - accessToken: [] parameters: - in: path - type: string name: deviceId description: The device to update. required: true - x-example: "QBUAZIFURK" - - in: body - name: body - required: true - description: New information for the device. + example: QBUAZIFURK schema: - type: object - properties: - display_name: - type: string - description: |- - The new display name for this device. If not given, the - display name is unchanged. - example: { "display_name": "My other phone" } + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + display_name: + type: string + description: |- + The new display name for this device. If not given, the + display name is unchanged. + example: { + "display_name": "My other phone" + } + description: New information for the device. + required: true responses: - 200: + "200": description: The device was successfully updated. - examples: - application/json: { - } - schema: - type: object # empty json object - 404: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "404": description: The current user has no device with the given ID. tags: - Device management @@ -145,41 +143,46 @@ paths: - accessToken: [] parameters: - in: path - type: string name: deviceId description: The device to delete. required: true - x-example: "QBUAZIFURK" - - in: body - name: body - required: true + example: QBUAZIFURK schema: - type: object - properties: - auth: - description: |- - Additional authentication information for the - user-interactive authentication API. - allOf: - - "$ref": "definitions/auth_data.yaml" + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + auth: + description: |- + Additional authentication information for the + user-interactive authentication API. + allOf: + - $ref: definitions/auth_data.yaml + required: true responses: - 200: + "200": description: |- The device was successfully removed, or had been removed previously. - schema: - type: object - examples: - application/json: { - } - 401: - description: |- - The homeserver requires additional authentication information. - schema: - "$ref": "definitions/auth_response.yaml" + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "401": + description: The homeserver requires additional authentication information. + content: + application/json: + schema: + $ref: definitions/auth_response.yaml tags: - Device management - "/delete_devices": + /delete_devices: post: summary: Bulk deletion of devices description: |- @@ -189,42 +192,62 @@ paths: operationId: deleteDevices security: - accessToken: [] - parameters: - - in: body - name: body - required: true - schema: - type: object - properties: - devices: - type: array - description: The list of device IDs to delete. - items: - type: string - description: A list of device IDs. - example: ["QBUAZIFURK", "AUIECTSRND"] - auth: - allOf: - - "$ref": "definitions/auth_data.yaml" - description: |- + requestBody: + content: + application/json: + schema: + type: object + properties: + devices: + type: array + description: The list of device IDs to delete. + items: + type: string + description: A list of device IDs. + example: + - QBUAZIFURK + - AUIECTSRND + auth: + allOf: + - $ref: definitions/auth_data.yaml + description: |- Additional authentication information for the user-interactive authentication API. - required: - - devices + required: + - devices + required: true responses: - 200: + "200": description: |- The devices were successfully removed, or had been removed previously. - schema: - type: object - examples: - application/json: { - } - 401: - description: |- - The homeserver requires additional authentication information. - schema: - "$ref": "definitions/auth_response.yaml" + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "401": + description: The homeserver requires additional authentication information. + content: + application/json: + schema: + $ref: definitions/auth_response.yaml tags: - Device management +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 diff --git a/data/api/client-server/directory.yaml b/data/api/client-server/directory.yaml index 25b854e07..df29fbf8f 100644 --- a/data/api/client-server/directory.yaml +++ b/data/api/client-server/directory.yaml @@ -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 Directory 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 Directory API + version: 1.0.0 paths: "/directory/room/{roomAlias}": put: @@ -35,52 +24,64 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomAlias description: | The room alias to set. Its format is defined [in the appendices](/appendices/#room-aliases). required: true - x-example: "#monkeys:matrix.org" - - in: body - name: body - description: Information about this room alias. - required: true + example: "#monkeys:matrix.org" schema: - type: object - properties: - room_id: - type: string - description: The room ID to set. - required: ['room_id'] - example: { - "room_id": "!abnjk1jdasj98:capuchins.com" - } + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + room_id: + type: string + description: The room ID to set. + required: + - room_id + example: { + "room_id": "!abnjk1jdasj98:capuchins.com" + } + description: Information about this room alias. + required: true responses: - 200: + "200": description: The mapping was created. - examples: - application/json: {} - schema: - type: object - 400: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "400": description: The given `roomAlias` is not a valid room alias. - examples: - application/json: { - "errcode": "M_INVALID_PARAM", - "error": "Room alias invalid" - } - schema: - "$ref": "definitions/errors/error.yaml" - 409: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_INVALID_PARAM", + "error": "Room alias invalid" + } + "409": description: A room alias with that name already exists. - examples: - application/json: { - "errcode": "M_UNKNOWN", - "error": "Room alias #monkeys:matrix.org already exists." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_UNKNOWN", + "error": "Room alias #monkeys:matrix.org already exists." + } tags: - Room directory get: @@ -91,59 +92,68 @@ paths: The server will use the federation API to resolve the alias if the domain part of the alias does not correspond to the server's own domain. - operationId: getRoomIdByAlias parameters: - in: path - type: string name: roomAlias description: | The room alias. Its format is defined [in the appendices](/appendices/#room-aliases). required: true - x-example: "#monkeys:matrix.org" + example: "#monkeys:matrix.org" + schema: + type: string responses: - 200: + "200": description: The room ID and other information for this alias. - schema: - type: object - properties: - room_id: - type: string - description: The room ID for this room alias. - servers: - type: array - description: A list of servers that are aware of this room alias. - items: - type: string - description: A server which is aware of this room alias. - examples: - application/json: { - "room_id": "!abnjk1jdasj98:capuchins.com", - "servers": [ - "capuchins.com", - "matrix.org", - "another.com" - ] - } - 400: + content: + application/json: + schema: + type: object + properties: + room_id: + type: string + description: The room ID for this room alias. + servers: + type: array + description: A list of servers that are aware of this room alias. + items: + type: string + description: A server which is aware of this room alias. + examples: + response: + value: { + "room_id": "!abnjk1jdasj98:capuchins.com", + "servers": [ + "capuchins.com", + "matrix.org", + "another.com" + ] + } + "400": description: The given `roomAlias` is not a valid room alias. - examples: - application/json: { - "errcode": "M_INVALID_PARAM", - "error": "Room alias invalid" - } - schema: - "$ref": "definitions/errors/error.yaml" - 404: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_INVALID_PARAM", + "error": "Room alias invalid" + } + "404": description: There is no mapped room ID for this room alias. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Room alias #monkeys:matrix.org not found." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Room alias #monkeys:matrix.org not found." + } tags: - Room directory delete: @@ -160,36 +170,41 @@ paths: canonical alias event are recommended to, in addition to their other relevant permission checks, delete the alias and return a successful response even if the user does not have permission to update the `m.room.canonical_alias` event. - operationId: deleteRoomAlias security: - accessToken: [] parameters: - in: path - type: string name: roomAlias description: | The room alias to remove. Its format is defined [in the appendices](/appendices/#room-aliases). required: true - x-example: "#monkeys:matrix.org" + example: "#monkeys:matrix.org" + schema: + type: string responses: - 200: + "200": description: The mapping was deleted. - examples: - application/json: { - } - schema: - type: object - 404: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "404": description: There is no mapped room ID for this room alias. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Room alias #monkeys:example.org not found." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Room alias #monkeys:example.org not found." + } tags: - Room directory "/rooms/{roomId}/aliases": @@ -212,59 +227,86 @@ paths: Clients are recommended not to display this list of aliases prominently as they are not curated, unlike those listed in the `m.room.canonical_alias` state event. - operationId: getLocalAliases security: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room ID to find local aliases of. required: true - x-example: "!abc123:example.org" - responses: - 200: - description: |- - The list of local aliases for the room. - examples: - application/json: { - "aliases": [ - "#somewhere:example.com", - "#another:example.com", - "#hat_trick:example.com" - ] - } + example: "!abc123:example.org" schema: - type: object - properties: - aliases: - type: array - description: The server's local aliases on the room. Can be empty. - items: - type: string - required: ['aliases'] - 400: + type: string + responses: + "200": + description: The list of local aliases for the room. + content: + application/json: + schema: + type: object + properties: + aliases: + type: array + description: The server's local aliases on the room. Can be empty. + items: + type: string + required: + - aliases + examples: + response: + value: { + "aliases": [ + "#somewhere:example.com", + "#another:example.com", + "#hat_trick:example.com" + ] + } + "400": description: The given `roomAlias` is not a valid room alias. - examples: - application/json: { - "errcode": "M_INVALID_PARAM", - "error": "Room alias invalid" - } - schema: - "$ref": "definitions/errors/error.yaml" - 403: - description: The user is not permitted to retrieve the list of local aliases for the room. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "You are not a member of the room." - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_INVALID_PARAM", + "error": "Room alias invalid" + } + "403": + description: The user is not permitted to retrieve the list of local aliases for + the room. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You are not a member of the room." + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Room directory +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 diff --git a/data/api/client-server/event_context.yaml b/data/api/client-server/event_context.yaml index 4a2541a6d..0d740241a 100644 --- a/data/api/client-server/event_context.yaml +++ b/data/api/client-server/event_context.yaml @@ -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 Event Context 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 Event Context API + version: 1.0.0 paths: "/rooms/{roomId}/context/{eventId}": get: @@ -42,29 +31,31 @@ 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: path - type: string name: eventId description: The event to get context around. required: true - x-example: "$f3h4d129462ha:example.com" + example: $f3h4d129462ha:example.com + schema: + type: string - in: query - type: integer name: limit description: |- The maximum number of context events to return. The limit applies to the sum of the `events_before` and `events_after` arrays. The requested event ID is always returned in `event` even if `limit` is 0. Defaults to 10. - x-example: 3 + example: 3 + schema: + type: integer - in: query name: filter - type: string description: |- A JSON `RoomEventFilter` to filter the returned events with. The filter is only applied to `events_before`, `events_after`, and @@ -73,78 +64,94 @@ paths: homeserver prefers. See [Filtering](/client-server-api/#filtering) for more information. - x-example: "66696p746572" + example: 66696p746572 + schema: + type: string responses: - 200: + "200": description: The events and state surrounding the requested event. - schema: - type: object - description: The events and state surrounding the requested event. - properties: - start: - type: string - description: |- - A token that can be used to paginate backwards with. - end: - type: string - description: |- - A token that can be used to paginate forwards with. - events_before: - type: array - description: |- - A list of room events that happened just before the - requested event, in reverse-chronological order. - items: - $ref: "definitions/client_event.yaml" - event: - description: |- - Details of the requested event. - allOf: - - $ref: "definitions/client_event.yaml" - events_after: - type: array - description: |- - A list of room events that happened just after the - requested event, in chronological order. - items: - $ref: "definitions/client_event.yaml" - state: - type: array - description: |- - The state of the room at the last event returned. - items: - $ref: "definitions/client_event.yaml" - examples: - application/json: { - "end": "t29-57_2_0_2", - "events_after": [ - { - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" - } - ], - "event": { - "event_id": "$f3h4d129462ha:example.com", - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.message$m.image.yaml" - }, - "events_before": [ - { - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.message$m.file.yaml" - } - ], - "start": "t27-54_2_0_2", - "state": [ - { - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.create.yaml" - }, - { - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.member.yaml" - } - ] - } + content: + application/json: + schema: + type: object + description: The events and state surrounding the requested event. + properties: + start: + type: string + description: A token that can be used to paginate backwards with. + end: + type: string + description: A token that can be used to paginate forwards with. + events_before: + type: array + description: |- + A list of room events that happened just before the + requested event, in reverse-chronological order. + items: + $ref: definitions/client_event.yaml + event: + description: Details of the requested event. + allOf: + - $ref: definitions/client_event.yaml + events_after: + type: array + description: |- + A list of room events that happened just after the + requested event, in chronological order. + items: + $ref: definitions/client_event.yaml + state: + type: array + description: The state of the room at the last event returned. + items: + $ref: definitions/client_event.yaml + examples: + response: + value: { + "end": "t29-57_2_0_2", + "events_after": [ + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + } + ], + "event": { + "event_id": "$f3h4d129462ha:example.com", + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.message$m.image.yaml" + }, + "events_before": [ + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.message$m.file.yaml" + } + ], + "start": "t27-54_2_0_2", + "state": [ + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.create.yaml" + }, + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.member.yaml" + } + ] + } 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 diff --git a/data/api/client-server/filter.yaml b/data/api/client-server/filter.yaml index d5575ff59..8405f81e6 100644 --- a/data/api/client-server/filter.yaml +++ b/data/api/client-server/filter.yaml @@ -11,20 +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 filter API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server filter API + version: 1.0.0 paths: "/user/{userId}/filter": post: @@ -38,61 +28,90 @@ paths: - accessToken: [] parameters: - in: path - type: string name: userId required: true - description: - The id of the user uploading the filter. The access token must be + description: The id of the user uploading the filter. The access token must be authorized to make requests for this user id. - x-example: "@alice:example.com" - - in: body - name: filter - required: true - description: The filter to upload. + example: "@alice:example.com" schema: - type: object - allOf: - - $ref: "definitions/sync_filter.yaml" - example: { - "room": { - "state": { - "types": ["m.room.*"], - "not_rooms": ["!726s6s6q:example.com"] + type: string + requestBody: + content: + application/json: + schema: + type: object + allOf: + - $ref: definitions/sync_filter.yaml + example: { + "room": { + "state": { + "types": [ + "m.room.*" + ], + "not_rooms": [ + "!726s6s6q:example.com" + ] + }, + "timeline": { + "limit": 10, + "types": [ + "m.room.message" + ], + "not_rooms": [ + "!726s6s6q:example.com" + ], + "not_senders": [ + "@spam:example.com" + ] + }, + "ephemeral": { + "types": [ + "m.receipt", + "m.typing" + ], + "not_rooms": [ + "!726s6s6q:example.com" + ], + "not_senders": [ + "@spam:example.com" + ] + } }, - "timeline": { - "limit": 10, - "types": ["m.room.message"], - "not_rooms": ["!726s6s6q:example.com"], - "not_senders": ["@spam:example.com"] + "presence": { + "types": [ + "m.presence" + ], + "not_senders": [ + "@alice:example.com" + ] }, - "ephemeral": { - "types": ["m.receipt", "m.typing"], - "not_rooms": ["!726s6s6q:example.com"], - "not_senders": ["@spam:example.com"] - } - }, - "presence": { - "types": ["m.presence"], - "not_senders": ["@alice:example.com"] - }, - "event_format": "client", - "event_fields": ["type", "content", "sender"] - } + "event_format": "client", + "event_fields": [ + "type", + "content", + "sender" + ] + } + description: The filter to upload. + required: true responses: - 200: + "200": description: The filter was created. - schema: - type: object - properties: - filter_id: - type: string - description: |- - The ID of the filter that was created. Cannot start - with a `{` as this character is used to determine - if the filter provided is inline JSON or a previously - declared filter by homeservers on some APIs. - example: "66696p746572" - required: ['filter_id'] + content: + application/json: + schema: + type: object + properties: + filter_id: + type: string + description: |- + The ID of the filter that was created. Cannot start + with a `{` as this character is used to determine + if the filter provided is inline JSON or a previously + declared filter by homeservers on some APIs. + example: 66696p746572 + required: + - filter_id tags: - Room participation "/user/{userId}/filter/{filterId}": @@ -104,53 +123,95 @@ paths: parameters: - in: path name: userId - type: string - description: |- - The user ID to download a filter for. - x-example: "@alice:example.com" + description: The user ID to download a filter for. required: true + example: "@alice:example.com" + schema: + type: string - in: path name: filterId - type: string - description: |- - The filter ID to download. - x-example: "66696p746572" + description: The filter ID to download. required: true + example: 66696p746572 + schema: + type: string responses: - 200: - description: |- - The filter definition. - examples: - application/json: { - "room": { - "state": { - "types": ["m.room.*"], - "not_rooms": ["!726s6s6q:example.com"] - }, - "timeline": { - "limit": 10, - "types": ["m.room.message"], - "not_rooms": ["!726s6s6q:example.com"], - "not_senders": ["@spam:example.com"] - }, - "ephemeral": { - "types": ["m.receipt", "m.typing"], - "not_rooms": ["!726s6s6q:example.com"], - "not_senders": ["@spam:example.com"] + "200": + description: The filter definition. + content: + application/json: + schema: + type: object + allOf: + - $ref: definitions/sync_filter.yaml + examples: + response: + value: { + "room": { + "state": { + "types": [ + "m.room.*" + ], + "not_rooms": [ + "!726s6s6q:example.com" + ] + }, + "timeline": { + "limit": 10, + "types": [ + "m.room.message" + ], + "not_rooms": [ + "!726s6s6q:example.com" + ], + "not_senders": [ + "@spam:example.com" + ] + }, + "ephemeral": { + "types": [ + "m.receipt", + "m.typing" + ], + "not_rooms": [ + "!726s6s6q:example.com" + ], + "not_senders": [ + "@spam:example.com" + ] + } + }, + "presence": { + "types": [ + "m.presence" + ], + "not_senders": [ + "@alice:example.com" + ] + }, + "event_format": "client", + "event_fields": [ + "type", + "content", + "sender" + ] } - }, - "presence": { - "types": ["m.presence"], - "not_senders": ["@alice:example.com"] - }, - "event_format": "client", - "event_fields": ["type", "content", "sender"] - } - schema: - type: object - allOf: - - $ref: "definitions/sync_filter.yaml" - 404: - description: "Unknown filter." + "404": + description: Unknown filter. 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 diff --git a/data/api/client-server/inviting.yaml b/data/api/client-server/inviting.yaml index 53439e95d..4c373c777 100644 --- a/data/api/client-server/inviting.yaml +++ b/data/api/client-server/inviting.yaml @@ -11,24 +11,11 @@ # 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 Room Joining 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 Room Joining API + version: 1.0.0 paths: - # With an extra " " to disambiguate from the 3pid invite endpoint - # The extra space makes it sort first for what I'm sure is a good reason. "/rooms/{roomId}/invite ": post: summary: Invite a user to participate in a particular room. @@ -47,48 +34,53 @@ paths: If the user was invited to the room, the homeserver will append a `m.room.member` event to the room. - operationId: inviteUser security: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room identifier (not alias) to which to invite the user. required: true - x-example: "!d41d8cd:matrix.org" - - in: body - name: body - required: true + example: "!d41d8cd:matrix.org" schema: - type: object - example: { - "user_id": "@cheeky_monkey:matrix.org", - "reason": "Welcome to the team!" - } - properties: - user_id: - type: string - description: The fully qualified user ID of the invitee. - reason: - x-addedInMatrixVersion: "1.1" - type: string - description: |- - Optional reason to be included as the `reason` on the subsequent - membership event. - required: ["user_id"] - responses: - 200: - description: The user has been invited to join the room, or was already invited to the room. - examples: - application/json: { + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { + "user_id": "@cheeky_monkey:matrix.org", + "reason": "Welcome to the team!" } - schema: - type: object - 400: + properties: + user_id: + type: string + description: The fully qualified user ID of the invitee. + reason: + x-addedInMatrixVersion: "1.1" + type: string + description: |- + Optional reason to be included as the `reason` on the subsequent + membership event. + required: + - user_id + required: true + responses: + "200": + description: The user has been invited to join the room, or was already invited + to the room. + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "400": description: |- - + The request is invalid. A meaningful `errcode` and description error text will be returned. Example reasons for rejection include: @@ -98,9 +90,11 @@ paths: - One or more users being invited to the room are residents of a homeserver which does not support the requested room version. The `errcode` will be `M_UNSUPPORTED_ROOM_VERSION` in these cases. - schema: - "$ref": "definitions/errors/error.yaml" - 403: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + "403": description: |- You do not have permission to invite the user to the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are: @@ -108,14 +102,36 @@ paths: - The invitee is already a member of the room. - The inviter is not currently in the room. - The inviter's power level is insufficient to invite users to the room. - examples: - application/json: { - "errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"} - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "@cheeky_monkey:matrix.org is banned from the room" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Room membership +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 diff --git a/data/api/client-server/joining.yaml b/data/api/client-server/joining.yaml index 48d630c42..35f56cac9 100644 --- a/data/api/client-server/joining.yaml +++ b/data/api/client-server/joining.yaml @@ -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 Room Inviting 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 Room Inviting API + version: 1.0.0 paths: "/rooms/{roomId}/join": post: @@ -47,48 +36,55 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room identifier (not alias) to join. required: true - x-example: "!d41d8cd:matrix.org" - - in: body - name: body - required: true + example: "!d41d8cd:matrix.org" schema: - type: object - properties: - third_party_signed: - allOf: - - $ref: "definitions/third_party_signed.yaml" - description: |- - If supplied, the homeserver must verify that it matches a pending - `m.room.third_party_invite` event in the room, and perform - key validity checking if required by the event. - reason: - x-addedInMatrixVersion: "1.1" - type: string - description: |- - Optional reason to be included as the `reason` on the subsequent - membership event. - example: "Looking for support" + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + third_party_signed: + allOf: + - $ref: definitions/third_party_signed.yaml + description: |- + If supplied, the homeserver must verify that it matches a pending + `m.room.third_party_invite` event in the room, and perform + key validity checking if required by the event. + reason: + x-addedInMatrixVersion: "1.1" + type: string + description: |- + Optional reason to be included as the `reason` on the subsequent + membership event. + example: Looking for support + required: true responses: - 200: + "200": description: |- The room has been joined. The joined room ID must be returned in the `room_id` field. - examples: - application/json: { - "room_id": "!d41d8cd:matrix.org"} - schema: - type: object - properties: - room_id: - type: string - description: The joined room ID. - required: ["room_id"] - 403: + content: + application/json: + schema: + type: object + properties: + room_id: + type: string + description: The joined room ID. + required: + - room_id + examples: + response: + value: { + "room_id": "!d41d8cd:matrix.org" + } + "403": description: |- You do not have permission to join the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejection are: @@ -96,15 +92,22 @@ paths: - The room is invite-only and the user was not invited. - The user has been banned from the room. - The room is restricted and the user failed to satisfy any of the conditions. - examples: - application/json: { - "errcode": "M_FORBIDDEN", "error": "You are not invited to this room."} - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You are not invited to this room." + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Room membership "/join/{roomIdOrAlias}": @@ -126,57 +129,69 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomIdOrAlias description: The room identifier or alias to join. required: true - x-example: "#monkeys:matrix.org" - - in: query - type: array - items: + example: "#monkeys:matrix.org" + schema: type: string + - in: query name: server_name description: |- The servers to attempt to join the room through. One of the servers must be participating in the room. - x-example: ["matrix.org", "elsewhere.ca"] - - in: body - name: body - required: true + example: + - matrix.org + - elsewhere.ca + style: form + explode: false schema: - type: object - properties: - third_party_signed: - allOf: - - $ref: "definitions/third_party_signed.yaml" - description: |- - If a `third_party_signed` was supplied, the homeserver must verify - that it matches a pending `m.room.third_party_invite` event in the - room, and perform key validity checking if required by the event. - reason: - x-addedInMatrixVersion: "1.1" - type: string - description: |- - Optional reason to be included as the `reason` on the subsequent - membership event. - example: "Looking for support" + type: array + items: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + third_party_signed: + allOf: + - $ref: definitions/third_party_signed.yaml + description: |- + If a `third_party_signed` was supplied, the homeserver must verify + that it matches a pending `m.room.third_party_invite` event in the + room, and perform key validity checking if required by the event. + reason: + x-addedInMatrixVersion: "1.1" + type: string + description: |- + Optional reason to be included as the `reason` on the subsequent + membership event. + example: Looking for support + required: true responses: - 200: + "200": description: |- The room has been joined. The joined room ID must be returned in the `room_id` field. - examples: - application/json: { - "room_id": "!d41d8cd:matrix.org"} - schema: - type: object - properties: - room_id: - type: string - description: The joined room ID. - required: ["room_id"] - 403: + content: + application/json: + schema: + type: object + properties: + room_id: + type: string + description: The joined room ID. + required: + - room_id + examples: + response: + value: { + "room_id": "!d41d8cd:matrix.org" + } + "403": description: |- You do not have permission to join the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejection are: @@ -184,14 +199,36 @@ paths: - The room is invite-only and the user was not invited. - The user has been banned from the room. - The room is restricted and the user failed to satisfy any of the conditions. - examples: - application/json: { - "errcode": "M_FORBIDDEN", "error": "You are not invited to this room."} - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You are not invited to this room." + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Room membership +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 diff --git a/data/api/client-server/key_backup.yaml b/data/api/client-server/key_backup.yaml index 0622d761d..cd7cf5a0b 100644 --- a/data/api/client-server/key_backup.yaml +++ b/data/api/client-server/key_backup.yaml @@ -11,164 +11,153 @@ # 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 Key Backup 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 Key Backup API + version: 1.0.0 paths: - "/room_keys/version": + /room_keys/version: post: x-addedInMatrixVersion: "1.1" summary: Create a new backup. - description: |- - Creates a new backup. + description: Creates a new backup. operationId: postRoomKeysVersion security: - accessToken: [] - parameters: - - in: body - name: version - description: "The backup configuration." - required: true - schema: - type: object - properties: - algorithm: - description: The algorithm used for storing backups. - type: string - enum: ["m.megolm_backup.v1.curve25519-aes-sha2"] - example: "m.megolm_backup.v1.curve25519-aes-sha2" - auth_data: - description: |- - Algorithm-dependent data. See the documentation for the backup - algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the - expected format of the data. - type: object - example: { - "public_key": "abcdefg", - "signatures": { - "@alice:example.org": { - "ed25519:deviceid": "signature" - } - } - } - required: - - algorithm - - auth_data + requestBody: + content: + application/json: + schema: + type: object + properties: + algorithm: + description: The algorithm used for storing backups. + type: string + enum: + - m.megolm_backup.v1.curve25519-aes-sha2 + example: m.megolm_backup.v1.curve25519-aes-sha2 + auth_data: + description: |- + Algorithm-dependent data. See the documentation for the backup + algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the + expected format of the data. + type: object + example: + public_key: abcdefg + signatures: + "@alice:example.org": + ed25519:deviceid: signature + required: + - algorithm + - auth_data + description: The backup configuration. + required: true responses: - 200: - description: - The version id of the new backup. - schema: - type: object - properties: - version: - type: string - description: The backup version. This is an opaque string. - example: "1" - required: - - version - 429: + "200": + description: The version id of the new backup. + content: + application/json: + schema: + type: object + properties: + version: + type: string + description: The backup version. This is an opaque string. + example: "1" + required: + - version + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - End-to-end encryption get: x-addedInMatrixVersion: "1.1" summary: Get information about the latest backup version. - description: |- - Get information about the latest backup version. + description: Get information about the latest backup version. operationId: getRoomKeysVersionCurrent security: - accessToken: [] responses: - 200: - description: - The information about the backup. - schema: - type: object - properties: - algorithm: - type: string - description: The algorithm used for storing backups. - enum: ["m.megolm_backup.v1.curve25519-aes-sha2"] - example: "m.megolm_backup.v1.curve25519-aes-sha2" - auth_data: - description: |- - Algorithm-dependent data. See the documentation for the backup - algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the - expected format of the data. + "200": + description: The information about the backup. + content: + application/json: + schema: type: object - example: { - "public_key": "abcdefg", - "signatures": { - "@alice:example.org": { - "ed25519:deviceid": "signature" - } + properties: + algorithm: + type: string + description: The algorithm used for storing backups. + enum: + - m.megolm_backup.v1.curve25519-aes-sha2 + example: m.megolm_backup.v1.curve25519-aes-sha2 + auth_data: + description: |- + Algorithm-dependent data. See the documentation for the backup + algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the + expected format of the data. + type: object + example: + public_key: abcdefg + signatures: + "@alice:example.org": + ed25519:deviceid: signature + count: + description: The number of keys stored in the backup. + type: integer + example: 42 + etag: + description: |- + An opaque string representing stored keys in the backup. + Clients can compare it with the `etag` value they received + in the request of their last key storage request. If not + equal, another client has modified the backup. + type: string + example: anopaquestring + version: + type: string + description: The backup version. + example: "1" + required: + - algorithm + - auth_data + - count + - etag + - version + "404": + description: No backup exists. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "No current backup version" } - } - count: - description: The number of keys stored in the backup. - type: integer - example: 42 - etag: - description: |- - An opaque string representing stored keys in the backup. - Clients can compare it with the `etag` value they received - in the request of their last key storage request. If not - equal, another client has modified the backup. - type: string - example: "anopaquestring" - version: - type: string - description: The backup version. - example: "1" - required: - - algorithm - - auth_data - - count - - etag - - version - 404: - description: - No backup exists. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "No current backup version" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - End-to-end encryption "/room_keys/version/{version}": get: x-addedInMatrixVersion: "1.1" summary: Get information about an existing backup. - description: |- - Get information about an existing backup. + description: Get information about an existing backup. operationId: getRoomKeysVersion security: - accessToken: [] parameters: - in: path - type: string name: version description: |- The backup version to get, as returned in the `version` parameter @@ -176,82 +165,86 @@ paths: [`POST /_matrix/client/v3/room_keys/version`](/client-server-api/#post_matrixclientv3room_keysversion) or this endpoint. required: true - x-example: "1" - responses: - 200: - description: - The information about the requested backup. + example: "1" schema: - type: object - properties: - algorithm: - type: string - description: The algorithm used for storing backups. - enum: ["m.megolm_backup.v1.curve25519-aes-sha2"] - example: "m.megolm_backup.v1.curve25519-aes-sha2" - auth_data: - description: |- - Algorithm-dependent data. See the documentation for the backup - algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the - expected format of the data. + type: string + responses: + "200": + description: The information about the requested backup. + content: + application/json: + schema: type: object - example: { - "public_key": "abcdefg", - "signatures": { - "@alice:example.org": { - "ed25519:deviceid": "signature" - } + properties: + algorithm: + type: string + description: The algorithm used for storing backups. + enum: + - m.megolm_backup.v1.curve25519-aes-sha2 + example: m.megolm_backup.v1.curve25519-aes-sha2 + auth_data: + description: |- + Algorithm-dependent data. See the documentation for the backup + algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the + expected format of the data. + type: object + example: + public_key: abcdefg + signatures: + "@alice:example.org": + ed25519:deviceid: signature + count: + description: The number of keys stored in the backup. + type: integer + example: 42 + etag: + description: |- + An opaque string representing stored keys in the backup. + Clients can compare it with the `etag` value they received + in the request of their last key storage request. If not + equal, another client has modified the backup. + type: string + example: anopaquestring + version: + type: string + description: The backup version. + example: "1" + required: + - algorithm + - auth_data + - count + - etag + - version + "404": + description: The backup specified does not exist. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Unknown backup version" } - } - count: - description: The number of keys stored in the backup. - type: integer - example: 42 - etag: - description: |- - An opaque string representing stored keys in the backup. - Clients can compare it with the `etag` value they received - in the request of their last key storage request. If not - equal, another client has modified the backup. - type: string - example: "anopaquestring" - version: - type: string - description: The backup version. - example: "1" - required: - - algorithm - - auth_data - - count - - etag - - version - 404: - description: - The backup specified does not exist. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Unknown backup version" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - End-to-end encryption put: x-addedInMatrixVersion: "1.1" summary: Update information about an existing backup. - description: |- - Update information about an existing backup. Only `auth_data` can be modified. + description: Update information about an existing backup. Only `auth_data` can + be modified. operationId: putRoomKeysVersion security: - accessToken: [] parameters: - in: path - type: string name: version description: |- The backup version to update, as returned in the `version` @@ -259,76 +252,88 @@ paths: [`POST /_matrix/client/v3/room_keys/version`](/client-server-api/#post_matrixclientv3room_keysversion) or [`GET /_matrix/client/v3/room_keys/version/{version}`](/client-server-api/#get_matrixclientv3room_keysversionversion). required: true - x-example: "1" - - in: body - name: version - description: "The backup configuration" - required: true + example: "1" schema: - type: object - properties: - algorithm: - description: |- - The algorithm used for storing backups. Must be the same as - the algorithm currently used by the backup. - type: string - enum: ["m.megolm_backup.v1.curve25519-aes-sha2"] - example: "m.megolm_backup.v1.curve25519-aes-sha2" - auth_data: - description: |- - Algorithm-dependent data. See the documentation for the backup - algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the - expected format of the data. - type: object - example: { - "public_key": "abcdefg", - "signatures": { - "@alice:example.org": { - "ed25519:deviceid": "signature" - } - } - } - version: - description: |- - The backup version. If present, must be the same as the - version in the path parameter. - type: string - example: "1" - required: - - algorithm - - auth_data + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + algorithm: + description: |- + The algorithm used for storing backups. Must be the same as + the algorithm currently used by the backup. + type: string + enum: + - m.megolm_backup.v1.curve25519-aes-sha2 + example: m.megolm_backup.v1.curve25519-aes-sha2 + auth_data: + description: |- + Algorithm-dependent data. See the documentation for the backup + algorithms in [Server-side key backups](/client-server-api/#server-side-key-backups) for more information on the + expected format of the data. + type: object + example: + public_key: abcdefg + signatures: + "@alice:example.org": + ed25519:deviceid: signature + version: + description: |- + The backup version. If present, must be the same as the + version in the path parameter. + type: string + example: "1" + required: + - algorithm + - auth_data + description: The backup configuration + required: true responses: - 200: + "200": description: The update succeeded. - examples: - application/json: {} - schema: - type: object - 400: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "400": description: |- A parameter was incorrect. For example, the `algorithm` does not match the current backup algorithm, or the `version` in the body does not match the `version` in the path. - examples: - application/json: { - "errcode": "M_INVALID_PARAM", - "error": "Algorithm does not match" - } - schema: - "$ref": "definitions/errors/error.yaml" - 404: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_INVALID_PARAM", + "error": "Algorithm does not match" + } + "404": description: The backup specified does not exist. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Unknown backup version" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Unknown backup version" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - End-to-end encryption delete: @@ -342,7 +347,6 @@ paths: - accessToken: [] parameters: - in: path - type: string name: version description: |- The backup version to delete, as returned in the `version` @@ -350,611 +354,689 @@ paths: [`POST /_matrix/client/v3/room_keys/version`](/client-server-api/#post_matrixclientv3room_keysversion) or [`GET /_matrix/client/v3/room_keys/version/{version}`](/client-server-api/#get_matrixclientv3room_keysversionversion). required: true - x-example: "1" + example: "1" + schema: + type: string responses: - 200: + "200": description: |- The delete succeeded, or the specified backup was previously deleted. - schema: - type: object - properties: {} - 404: + content: + application/json: + schema: + type: object + properties: {} + "404": description: |- The backup specified does not exist. If the backup was previously deleted, the call should succeed rather than returning an error. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Unknown backup version" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Unknown backup version" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - End-to-end encryption "/room_keys/keys/{roomId}/{sessionId}": put: x-addedInMatrixVersion: "1.1" summary: Store a key in the backup. - description: |- - Store a key in the backup. + description: Store a key in the backup. operationId: putRoomKeyBySessionId security: - accessToken: [] parameters: - in: query - type: string name: version - description: |- - The backup in which to store the key. Must be the current backup. + description: The backup in which to store the key. Must be the current backup. required: true - x-example: "1" + example: "1" + schema: + type: string - in: path - type: string name: roomId description: The ID of the room that the key is for. required: true - x-example: "!roomid:example.org" + example: "!roomid:example.org" + schema: + type: string - in: path - type: string name: sessionId description: The ID of the megolm session that the key is for. required: true - x-example: "sessionid" - - in: body - name: data - description: "The key data." - required: true + example: sessionid schema: - "$ref": "definitions/key_backup_data.yaml" + type: string + requestBody: + content: + application/json: + schema: + $ref: definitions/key_backup_data.yaml + description: The key data. + required: true responses: - 200: + "200": description: The update succeeded. - schema: - type: object - title: RoomKeysUpdateResponse - properties: - etag: - description: |- - The new etag value representing stored keys in the backup. - See `GET /room_keys/version/{version}` for more details. - type: string - example: "abcdefg" - count: - description: The number of keys stored in the backup - type: integer - example: 10 - required: - - etag - - count - 403: + content: + application/json: + schema: + type: object + title: RoomKeysUpdateResponse + properties: + etag: + description: |- + The new etag value representing stored keys in the backup. + See `GET /room_keys/version/{version}` for more details. + type: string + example: abcdefg + count: + description: The number of keys stored in the backup + type: integer + example: 10 + required: + - etag + - count + "403": description: |- The version specified does not match the current backup version. The current version will be included in the `current_version` field. - examples: - application/json: { - "errcode": "M_WRONG_ROOM_KEYS_VERSION", - "error": "Wrong backup version.", - "current_version": "42" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_WRONG_ROOM_KEYS_VERSION", + "error": "Wrong backup version.", + "current_version": "42" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - End-to-end encryption get: x-addedInMatrixVersion: "1.1" summary: Retrieve a key from the backup. - description: |- - Retrieve a key from the backup. + description: Retrieve a key from the backup. operationId: getRoomKeyBySessionId security: - accessToken: [] parameters: - in: query - type: string name: version - description: |- - The backup from which to retrieve the key. + description: The backup from which to retrieve the key. required: true - x-example: "1" + example: "1" + schema: + type: string - in: path - type: string name: roomId description: The ID of the room that the requested key is for. required: true - x-example: "!roomid:example.org" + example: "!roomid:example.org" + schema: + type: string - in: path - type: string name: sessionId description: The ID of the megolm session whose key is requested. required: true - x-example: "sessionid" + example: sessionid + schema: + type: string responses: - 200: + "200": description: The key data - schema: - "$ref": "definitions/key_backup_data.yaml" - 404: + content: + application/json: + schema: + $ref: definitions/key_backup_data.yaml + "404": description: The key or backup was not found. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Key not found." - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Key not found." + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - End-to-end encryption delete: x-addedInMatrixVersion: "1.1" summary: Delete a key from the backup. - description: |- - Delete a key from the backup. + description: Delete a key from the backup. operationId: deleteRoomKeyBySessionId security: - accessToken: [] parameters: - in: query - type: string name: version - description: |- - The backup from which to delete the key + description: The backup from which to delete the key required: true - x-example: "1" + example: "1" + schema: + type: string - in: path - type: string name: roomId description: The ID of the room that the specified key is for. required: true - x-example: "!roomid:example.org" + example: "!roomid:example.org" + schema: + type: string - in: path - type: string name: sessionId description: The ID of the megolm session whose key is to be deleted. required: true - x-example: "sessionid" + example: sessionid + schema: + type: string responses: - 200: + "200": description: The update succeeded - schema: - type: object - title: RoomKeysUpdateResponse - properties: - etag: - description: |- - The new etag value representing stored keys in the backup. - See `GET /room_keys/version/{version}` for more details. - type: string - example: "abcdefg" - count: - description: The number of keys stored in the backup - type: integer - example: 10 - required: - - etag - - count - 404: - description: |- - The backup was not found. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Unknown backup version" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + type: object + title: RoomKeysUpdateResponse + properties: + etag: + description: |- + The new etag value representing stored keys in the backup. + See `GET /room_keys/version/{version}` for more details. + type: string + example: abcdefg + count: + description: The number of keys stored in the backup + type: integer + example: 10 + required: + - etag + - count + "404": + description: The backup was not found. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Unknown backup version" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - End-to-end encryption "/room_keys/keys/{roomId}": put: x-addedInMatrixVersion: "1.1" summary: Store several keys in the backup for a given room. - description: |- - Store several keys in the backup for a given room. + description: Store several keys in the backup for a given room. operationId: putRoomKeysByRoomId security: - accessToken: [] parameters: - in: query - type: string name: version - description: |- - The backup in which to store the keys. Must be the current backup. + description: The backup in which to store the keys. Must be the current backup. required: true - x-example: "1" + example: "1" + schema: + type: string - in: path - type: string name: roomId description: The ID of the room that the keys are for. required: true - x-example: "!roomid:example.org" - - in: body - description: "The backup data" - name: backupData - required: true + example: "!roomid:example.org" schema: - $ref: "definitions/room_key_backup.yaml" + type: string + requestBody: + content: + application/json: + schema: + $ref: definitions/room_key_backup.yaml + description: The backup data + required: true responses: - 200: + "200": description: The update succeeded - schema: - type: object - title: RoomKeysUpdateResponse - properties: - etag: - description: |- - The new etag value representing stored keys in the backup. - See `GET /room_keys/version/{version}` for more details. - type: string - example: "abcdefg" - count: - description: The number of keys stored in the backup - type: integer - example: 10 - required: - - etag - - count - 403: + content: + application/json: + schema: + type: object + title: RoomKeysUpdateResponse + properties: + etag: + description: |- + The new etag value representing stored keys in the backup. + See `GET /room_keys/version/{version}` for more details. + type: string + example: abcdefg + count: + description: The number of keys stored in the backup + type: integer + example: 10 + required: + - etag + - count + "403": description: |- The version specified does not match the current backup version. The current version will be included in the `current_version` field. - examples: - application/json: { - "errcode": "M_WRONG_ROOM_KEYS_VERSION", - "error": "Wrong backup version.", - "current_version": "42" - } - schema: - "$ref": "definitions/errors/error.yaml" - 404: - description: |- - The backup was not found. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Unknown backup version" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_WRONG_ROOM_KEYS_VERSION", + "error": "Wrong backup version.", + "current_version": "42" + } + "404": + description: The backup was not found. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Unknown backup version" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - End-to-end encryption get: x-addedInMatrixVersion: "1.1" summary: Retrieve the keys from the backup for a given room. - description: |- - Retrieve the keys from the backup for a given room. + description: Retrieve the keys from the backup for a given room. operationId: getRoomKeysByRoomId security: - accessToken: [] parameters: - in: query - type: string name: version - description: |- - The backup from which to retrieve the key. + description: The backup from which to retrieve the key. required: true - x-example: "1" + example: "1" + schema: + type: string - in: path - type: string name: roomId description: The ID of the room that the requested key is for. required: true - x-example: "!roomid:example.org" + example: "!roomid:example.org" + schema: + type: string responses: - 200: + "200": description: |- The key data. If no keys are found, then an object with an empty `sessions` property will be returned (`{"sessions": {}}`). - schema: - type: object - $ref: "definitions/room_key_backup.yaml" - 404: - description: |- - The backup was not found. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Unknown backup version" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + type: object + $ref: definitions/room_key_backup.yaml + "404": + description: The backup was not found. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Unknown backup version" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - End-to-end encryption delete: x-addedInMatrixVersion: "1.1" summary: Delete the keys from the backup for a given room. - description: |- - Delete the keys from the backup for a given room. + description: Delete the keys from the backup for a given room. operationId: deleteRoomKeysByRoomId security: - accessToken: [] parameters: - in: query - type: string name: version - description: |- - The backup from which to delete the key. + description: The backup from which to delete the key. required: true - x-example: "1" + example: "1" + schema: + type: string - in: path - type: string name: roomId description: The ID of the room that the specified key is for. required: true - x-example: "!roomid:example.org" + example: "!roomid:example.org" + schema: + type: string responses: - 200: + "200": description: The update succeeded - schema: - type: object - title: RoomKeysUpdateResponse - properties: - etag: - description: |- - The new etag value representing stored keys in the backup. - See `GET /room_keys/version/{version}` for more details. - type: string - example: "abcdefg" - count: - description: The number of keys stored in the backup - type: integer - example: 10 - required: - - etag - - count - 404: - description: |- - The backup was not found. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Unknown backup version" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + type: object + title: RoomKeysUpdateResponse + properties: + etag: + description: |- + The new etag value representing stored keys in the backup. + See `GET /room_keys/version/{version}` for more details. + type: string + example: abcdefg + count: + description: The number of keys stored in the backup + type: integer + example: 10 + required: + - etag + - count + "404": + description: The backup was not found. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Unknown backup version" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - End-to-end encryption - "/room_keys/keys": + /room_keys/keys: put: x-addedInMatrixVersion: "1.1" summary: Store several keys in the backup. - description: |- - Store several keys in the backup. + description: Store several keys in the backup. operationId: putRoomKeys security: - accessToken: [] parameters: - in: query - type: string name: version - description: |- - The backup in which to store the keys. Must be the current backup. - required: true - x-example: "1" - - in: body - description: "The backup data." - name: backupData + description: The backup in which to store the keys. Must be the current backup. required: true + example: "1" schema: - type: object - properties: - rooms: - type: object - description: |- - A map of room IDs to room key backup data. - additionalProperties: - allOf: - - $ref: "definitions/room_key_backup.yaml" - example: { - "!room:example.org": { - "sessions": { - "sessionid1": { - "first_message_index": 1, - "forwarded_count": 0, - "is_verified": true, - "session_data": { - "ephemeral": "base64+ephemeral+key", - "ciphertext": "base64+ciphertext+of+JSON+data", - "mac": "base64+mac+of+ciphertext" - } - } - } - } - } - required: - - rooms + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + rooms: + type: object + description: A map of room IDs to room key backup data. + additionalProperties: + allOf: + - $ref: definitions/room_key_backup.yaml + example: + "!room:example.org": + sessions: + sessionid1: + first_message_index: 1 + forwarded_count: 0 + is_verified: true + session_data: + ephemeral: base64+ephemeral+key + ciphertext: base64+ciphertext+of+JSON+data + mac: base64+mac+of+ciphertext + required: + - rooms + description: The backup data. + required: true responses: - 200: + "200": description: The update succeeded - schema: - type: object - title: RoomKeysUpdateResponse - properties: - etag: - description: |- - The new etag value representing stored keys in the backup. - See `GET /room_keys/version/{version}` for more details. - type: string - example: "abcdefg" - count: - description: The number of keys stored in the backup - type: integer - example: 10 - required: - - etag - - count - 403: + content: + application/json: + schema: + type: object + title: RoomKeysUpdateResponse + properties: + etag: + description: |- + The new etag value representing stored keys in the backup. + See `GET /room_keys/version/{version}` for more details. + type: string + example: abcdefg + count: + description: The number of keys stored in the backup + type: integer + example: 10 + required: + - etag + - count + "403": description: |- The version specified does not match the current backup version. The current version will be included in the `current_version` field. - examples: - application/json: { - "errcode": "M_WRONG_ROOM_KEYS_VERSION", - "error": "Wrong backup version.", - "current_version": "42" - } - schema: - "$ref": "definitions/errors/error.yaml" - 404: - description: |- - The backup was not found. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Unknown backup version" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_WRONG_ROOM_KEYS_VERSION", + "error": "Wrong backup version.", + "current_version": "42" + } + "404": + description: The backup was not found. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Unknown backup version" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - End-to-end encryption get: x-addedInMatrixVersion: "1.1" summary: Retrieve the keys from the backup. - description: |- - Retrieve the keys from the backup. + description: Retrieve the keys from the backup. operationId: getRoomKeys security: - accessToken: [] parameters: - in: query - type: string name: version - description: |- - The backup from which to retrieve the keys. + description: The backup from which to retrieve the keys. required: true - x-example: "1" + example: "1" + schema: + type: string responses: - 200: + "200": description: |- The key data. If no keys are found, then an object with an empty `rooms` property will be returned (`{"rooms": {}}`). - schema: - type: object - properties: - rooms: + content: + application/json: + schema: type: object - description: |- - A map of room IDs to room key backup data. - additionalProperties: - allOf: - - $ref: "definitions/room_key_backup.yaml" - example: { - "!room:example.org": { - "sessions": { - "sessionid1": { - "first_message_index": 1, - "forwarded_count": 0, - "is_verified": true, - "session_data": { - "ephemeral": "base64+ephemeral+key", - "ciphertext": "base64+ciphertext+of+JSON+data", - "mac": "base64+mac+of+ciphertext" - } - } - } - } - } - required: - - rooms - 404: + properties: + rooms: + type: object + description: A map of room IDs to room key backup data. + additionalProperties: + allOf: + - $ref: definitions/room_key_backup.yaml + example: + "!room:example.org": + sessions: + sessionid1: + first_message_index: 1 + forwarded_count: 0 + is_verified: true + session_data: + ephemeral: base64+ephemeral+key + ciphertext: base64+ciphertext+of+JSON+data + mac: base64+mac+of+ciphertext + required: + - rooms + "404": description: The backup was not found. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Unknown backup version." - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Unknown backup version." + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - End-to-end encryption delete: x-addedInMatrixVersion: "1.1" summary: Delete the keys from the backup. - description: |- - Delete the keys from the backup. + description: Delete the keys from the backup. operationId: deleteRoomKeys security: - accessToken: [] parameters: - in: query - type: string name: version - description: |- - The backup from which to delete the key + description: The backup from which to delete the key required: true - x-example: "1" + example: "1" + schema: + type: string responses: - 200: + "200": description: The update succeeded - schema: - type: object - title: RoomKeysUpdateResponse - properties: - etag: - description: |- - The new etag value representing stored keys in the backup. - See `GET /room_keys/version/{version}` for more details. - type: string - example: "abcdefg" - count: - description: The number of keys stored in the backup - type: integer - example: 10 - required: - - etag - - count - 404: - description: |- - The backup was not found. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Unknown backup version" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + type: object + title: RoomKeysUpdateResponse + properties: + etag: + description: |- + The new etag value representing stored keys in the backup. + See `GET /room_keys/version/{version}` for more details. + type: string + example: abcdefg + count: + description: The number of keys stored in the backup + type: integer + example: 10 + required: + - etag + - count + "404": + description: The backup was not found. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Unknown backup version" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - End-to-end encryption +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 diff --git a/data/api/client-server/keys.yaml b/data/api/client-server/keys.yaml index 137295c52..3f6bc8060 100644 --- a/data/api/client-server/keys.yaml +++ b/data/api/client-server/keys.yaml @@ -13,414 +13,354 @@ # 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 Client Config 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 Client Config API + version: 1.0.0 paths: - "/keys/upload": + /keys/upload: post: summary: Upload end-to-end encryption keys. - description: |- - Publishes end-to-end encryption keys for the device. + description: Publishes end-to-end encryption keys for the device. operationId: uploadKeys security: - accessToken: [] - parameters: - - in: body - name: keys - description: |- - The keys to be published - required: true - schema: - type: object - properties: - device_keys: - description: |- - Identity keys for the device. May be absent if no new - identity keys are required. - allOf: - - $ref: definitions/device_keys.yaml - one_time_keys: - # $ref: "definitions/one_time_keys.yaml" - # XXX: We can't define an actual object here, so we have to hope - # that people will look at the swagger source or can figure it out - # from the other endpoints/example. - type: object - title: OneTimeKeys - description: |- - One-time public keys for "pre-key" messages. The names of - the properties should be in the format - `:`. The format of the key is determined - by the [key algorithm](/client-server-api/#key-algorithms). + requestBody: + content: + application/json: + schema: + type: object + properties: + device_keys: + description: |- + Identity keys for the device. May be absent if no new + identity keys are required. + allOf: + - $ref: definitions/device_keys.yaml + one_time_keys: + type: object + title: OneTimeKeys + description: |- + One-time public keys for "pre-key" messages. The names of + the properties should be in the format + `:`. The format of the key is determined + by the [key algorithm](/client-server-api/#key-algorithms). - May be absent if no new one-time keys are required. - example: { - "curve25519:AAAAAQ": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8", - "signed_curve25519:AAAAHg": { - "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs", - "signatures": { - "@alice:example.com": { - "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw" - } - } - }, - "signed_curve25519:AAAAHQ": { - "key": "j3fR3HemM16M7CWhoI4Sk5ZsdmdfQHsKL1xuSft6MSw", - "signatures": { - "@alice:example.com": { - "ed25519:JLAFKJWSCS": "IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA" - } - } - } - } - fallback_keys: - x-addedInMatrixVersion: "1.2" - # $ref: "definitions/one_time_keys.yaml" - # XXX: We can't define an actual object here - see above. - type: object - title: OneTimeKeys - description: |- - The public key which should be used if the device's one-time keys - are exhausted. The fallback key is not deleted once used, but should - be replaced when additional one-time keys are being uploaded. The - server will notify the client of the fallback key being used through - `/sync`. + May be absent if no new one-time keys are required. + example: + curve25519:AAAAAQ: /qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8 + signed_curve25519:AAAAHg: + key: zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs + signatures: + "@alice:example.com": + ed25519:JLAFKJWSCS: FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw + signed_curve25519:AAAAHQ: + key: j3fR3HemM16M7CWhoI4Sk5ZsdmdfQHsKL1xuSft6MSw + signatures: + "@alice:example.com": + ed25519:JLAFKJWSCS: IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA + fallback_keys: + x-addedInMatrixVersion: "1.2" + type: object + title: OneTimeKeys + description: |- + The public key which should be used if the device's one-time keys + are exhausted. The fallback key is not deleted once used, but should + be replaced when additional one-time keys are being uploaded. The + server will notify the client of the fallback key being used through + `/sync`. - There can only be at most one key per algorithm uploaded, and the server - will only persist one key per algorithm. + There can only be at most one key per algorithm uploaded, and the server + will only persist one key per algorithm. - When uploading a signed key, an additional `fallback: true` key should - be included to denote that the key is a fallback key. + When uploading a signed key, an additional `fallback: true` key should + be included to denote that the key is a fallback key. - May be absent if a new fallback key is not required. - example: { - "curve25519:AAAAAG": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8", - "signed_curve25519:AAAAGj": { - "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs", - "fallback": true, - "signatures": { - "@alice:example.com": { - "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw" - } - } - } - } + May be absent if a new fallback key is not required. + example: + curve25519:AAAAAG: /qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8 + signed_curve25519:AAAAGj: + key: zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs + fallback: true + signatures: + "@alice:example.com": + ed25519:JLAFKJWSCS: FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw + description: The keys to be published + required: true responses: - 200: - description: - The provided keys were successfully uploaded. - schema: - type: object - properties: - one_time_key_counts: + "200": + description: The provided keys were successfully uploaded. + content: + application/json: + schema: type: object - additionalProperties: - type: integer - description: |- - For each key algorithm, the number of unclaimed one-time keys - of that type currently held on the server for this device. - If an algorithm is not listed, the count for that algorithm - is to be assumed zero. - example: - curve25519: 10 - signed_curve25519: 20 - required: - - one_time_key_counts - + properties: + one_time_key_counts: + type: object + additionalProperties: + type: integer + description: |- + For each key algorithm, the number of unclaimed one-time keys + of that type currently held on the server for this device. + If an algorithm is not listed, the count for that algorithm + is to be assumed zero. + example: + curve25519: 10 + signed_curve25519: 20 + required: + - one_time_key_counts tags: - End-to-end encryption - "/keys/query": + /keys/query: post: summary: Download device identity keys. - description: |- - Returns the current devices and identity keys for the given users. + description: Returns the current devices and identity keys for the given users. operationId: queryKeys security: - accessToken: [] - parameters: - - in: body - name: query - description: |- - Query defining the keys to be downloaded - required: true - schema: - type: object - properties: - timeout: - type: integer - description: |- - The time (in milliseconds) to wait when downloading keys from - remote servers. 10 seconds is the recommended default. - example: 10000 - device_keys: - type: object - description: |- - The keys to be downloaded. A map from user ID, to a list of - device IDs, or to an empty list to indicate all devices for the - corresponding user. - additionalProperties: - type: array - items: - type: string - description: "device ID" - example: - "@alice:example.com": [] - required: - - device_keys - + requestBody: + content: + application/json: + schema: + type: object + properties: + timeout: + type: integer + description: |- + The time (in milliseconds) to wait when downloading keys from + remote servers. 10 seconds is the recommended default. + example: 10000 + device_keys: + type: object + description: |- + The keys to be downloaded. A map from user ID, to a list of + device IDs, or to an empty list to indicate all devices for the + corresponding user. + additionalProperties: + type: array + items: + type: string + description: device ID + example: + "@alice:example.com": [] + required: + - device_keys + description: Query defining the keys to be downloaded + required: true responses: - 200: - description: - The device information - schema: - type: object - properties: - failures: + "200": + description: The device information + content: + application/json: + schema: type: object - description: |- - If any remote homeservers could not be reached, they are - recorded here. The names of the properties are the names of - the unreachable servers. + properties: + failures: + type: object + description: |- + If any remote homeservers could not be reached, they are + recorded here. The names of the properties are the names of + the unreachable servers. - If the homeserver could be reached, but the user or device - was unknown, no failure is recorded. Instead, the corresponding - user or device is missing from the `device_keys` result. - additionalProperties: - type: object - example: {} - device_keys: - type: object - description: |- - Information on the queried devices. A map from user ID, to a - map from device ID to device information. For each device, - the information returned will be the same as uploaded via - `/keys/upload`, with the addition of an `unsigned` - property. - additionalProperties: - type: object - additionalProperties: - title: DeviceInformation - allOf: - - $ref: definitions/device_keys.yaml - properties: - unsigned: - title: UnsignedDeviceInfo - type: object - description: |- - Additional data added to the device key information - by intermediate servers, and not covered by the - signatures. + If the homeserver could be reached, but the user or device + was unknown, no failure is recorded. Instead, the corresponding + user or device is missing from the `device_keys` result. + additionalProperties: + type: object + example: {} + device_keys: + type: object + description: |- + Information on the queried devices. A map from user ID, to a + map from device ID to device information. For each device, + the information returned will be the same as uploaded via + `/keys/upload`, with the addition of an `unsigned` + property. + additionalProperties: + type: object + additionalProperties: + title: DeviceInformation + allOf: + - $ref: definitions/device_keys.yaml properties: - device_display_name: - type: string - description: - The display name which the user set on the device. - example: - "@alice:example.com": - JLAFKJWSCS: { - "user_id": "@alice:example.com", - "device_id": "JLAFKJWSCS", - "algorithms": [ - "m.olm.v1.curve25519-aes-sha2", - "m.megolm.v1.aes-sha2" - ], - "keys": { - "curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI", - "ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI" - }, - "signatures": { - "@alice:example.com": { - "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA" - } - }, - "unsigned": { - "device_display_name": "Alice's mobile phone" - } - } - master_keys: - x-addedInMatrixVersion: "1.1" - type: object - description: |- - Information on the master cross-signing keys of the queried users. - A map from user ID, to master key information. For each key, the - information returned will be the same as uploaded via - `/keys/device_signing/upload`, along with the signatures - uploaded via `/keys/signatures/upload` that the requesting user - is allowed to see. - additionalProperties: - allOf: - - $ref: definitions/cross_signing_key.yaml - example: { - "@alice:example.com": { - "user_id": "@alice:example.com", - "usage": ["master"], - "keys": { - "ed25519:base64+master+public+key": "base64+master+public+key", - } - } - } - self_signing_keys: - x-addedInMatrixVersion: "1.1" - type: object - description: |- - Information on the self-signing keys of the queried users. A map - from user ID, to self-signing key information. For each key, the - information returned will be the same as uploaded via - `/keys/device_signing/upload`. - additionalProperties: - allOf: - - $ref: definitions/cross_signing_key.yaml - example: { - "@alice:example.com": { - "user_id": "@alice:example.com", - "usage": ["self_signing"], - "keys": { - "ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key", - }, - "signatures": { - "@alice:example.com": { - "ed25519:base64+master+public+key": "signature+of+self+signing+key" - } - } - } - } - user_signing_keys: - type: object - description: |- - Information on the user-signing key of the user making the - request, if they queried their own device information. A map - from user ID, to user-signing key information. The - information returned will be the same as uploaded via - `/keys/device_signing/upload`. - additionalProperties: - allOf: - - $ref: definitions/cross_signing_key.yaml - example: { - "@alice:example.com": { - "user_id": "@alice:example.com", - "usage": ["user_signing"], - "keys": { - "ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key", - }, - "signatures": { - "@alice:example.com": { - "ed25519:base64+master+public+key": "signature+of+user+signing+key" - } - } - } - } + unsigned: + title: UnsignedDeviceInfo + type: object + description: |- + Additional data added to the device key information + by intermediate servers, and not covered by the + signatures. + properties: + device_display_name: + type: string + description: The display name which the user set on the device. + example: + "@alice:example.com": + JLAFKJWSCS: + user_id: "@alice:example.com" + device_id: JLAFKJWSCS + algorithms: + - m.olm.v1.curve25519-aes-sha2 + - m.megolm.v1.aes-sha2 + keys: + curve25519:JLAFKJWSCS: 3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI + ed25519:JLAFKJWSCS: lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI + signatures: + "@alice:example.com": + ed25519:JLAFKJWSCS: dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA + unsigned: + device_display_name: Alice's mobile phone + master_keys: + x-addedInMatrixVersion: "1.1" + type: object + description: |- + Information on the master cross-signing keys of the queried users. + A map from user ID, to master key information. For each key, the + information returned will be the same as uploaded via + `/keys/device_signing/upload`, along with the signatures + uploaded via `/keys/signatures/upload` that the requesting user + is allowed to see. + additionalProperties: + allOf: + - $ref: definitions/cross_signing_key.yaml + example: + "@alice:example.com": + user_id: "@alice:example.com" + usage: + - master + keys: + ed25519:base64+master+public+key: base64+master+public+key + self_signing_keys: + x-addedInMatrixVersion: "1.1" + type: object + description: |- + Information on the self-signing keys of the queried users. A map + from user ID, to self-signing key information. For each key, the + information returned will be the same as uploaded via + `/keys/device_signing/upload`. + additionalProperties: + allOf: + - $ref: definitions/cross_signing_key.yaml + example: + "@alice:example.com": + user_id: "@alice:example.com" + usage: + - self_signing + keys: + ed25519:base64+self+signing+public+key: base64+self+signing+master+public+key + signatures: + "@alice:example.com": + ed25519:base64+master+public+key: signature+of+self+signing+key + user_signing_keys: + type: object + description: |- + Information on the user-signing key of the user making the + request, if they queried their own device information. A map + from user ID, to user-signing key information. The + information returned will be the same as uploaded via + `/keys/device_signing/upload`. + additionalProperties: + allOf: + - $ref: definitions/cross_signing_key.yaml + example: + "@alice:example.com": + user_id: "@alice:example.com" + usage: + - user_signing + keys: + ed25519:base64+user+signing+public+key: base64+user+signing+master+public+key + signatures: + "@alice:example.com": + ed25519:base64+master+public+key: signature+of+user+signing+key tags: - End-to-end encryption - "/keys/claim": + /keys/claim: post: summary: Claim one-time encryption keys. - description: |- - Claims one-time keys for use in pre-key messages. + description: Claims one-time keys for use in pre-key messages. operationId: claimKeys security: - accessToken: [] - parameters: - - in: body - name: query - description: |- - Query defining the keys to be claimed - required: true - schema: - type: object - properties: - timeout: - type: integer - description: |- - The time (in milliseconds) to wait when downloading keys from - remote servers. 10 seconds is the recommended default. - example: 10000 - one_time_keys: - type: object - description: |- - The keys to be claimed. A map from user ID, to a map from - device ID to algorithm name. - additionalProperties: + requestBody: + content: + application/json: + schema: + type: object + properties: + timeout: + type: integer + description: |- + The time (in milliseconds) to wait when downloading keys from + remote servers. 10 seconds is the recommended default. + example: 10000 + one_time_keys: type: object + description: |- + The keys to be claimed. A map from user ID, to a map from + device ID to algorithm name. additionalProperties: - type: string - description: algorithm - example: "signed_curve25519" - example: { - "@alice:example.com": { "JLAFKJWSCS": "signed_curve25519" } - } - required: - - one_time_keys + type: object + additionalProperties: + type: string + description: algorithm + example: signed_curve25519 + example: + "@alice:example.com": + JLAFKJWSCS: signed_curve25519 + required: + - one_time_keys + description: Query defining the keys to be claimed + required: true responses: - 200: - description: - The claimed keys. - schema: - type: object - properties: - failures: + "200": + description: The claimed keys. + content: + application/json: + schema: type: object - description: |- - If any remote homeservers could not be reached, they are - recorded here. The names of the properties are the names of - the unreachable servers. + properties: + failures: + type: object + description: |- + If any remote homeservers could not be reached, they are + recorded here. The names of the properties are the names of + the unreachable servers. - If the homeserver could be reached, but the user or device - was unknown, no failure is recorded. Instead, the corresponding - user or device is missing from the `one_time_keys` result. - additionalProperties: - type: object - example: {} - one_time_keys: - type: object - description: |- - One-time keys for the queried devices. A map from user ID, to a - map from devices to a map from `:` to the key object. + If the homeserver could be reached, but the user or device + was unknown, no failure is recorded. Instead, the corresponding + user or device is missing from the `one_time_keys` result. + additionalProperties: + type: object + example: {} + one_time_keys: + type: object + description: |- + One-time keys for the queried devices. A map from user ID, to a + map from devices to a map from `:` to the key object. - See the [key algorithms](/client-server-api/#key-algorithms) section for information - on the Key Object format. + See the [key algorithms](/client-server-api/#key-algorithms) section for information + on the Key Object format. - If necessary, the claimed key might be a fallback key. Fallback - keys are re-used by the server until replaced by the device. - additionalProperties: - type: object - additionalProperties: - # $ref: "definitions/one_time_keys.yaml" - # XXX: We can't define an actual object here, so we have to hope - # that people will read the link provided in the description - # and figure it out from the other endpoints/example. - # See also one_time_key parameter for /keys/upload above. - type: object - title: OneTimeKeys - example: { - "@alice:example.com": { - "JLAFKJWSCS": { - "signed_curve25519:AAAAHg": { - "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs", - "signatures": { - "@alice:example.com": { - "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw" - } - } - } - } - } - } - required: ['one_time_keys'] + If necessary, the claimed key might be a fallback key. Fallback + keys are re-used by the server until replaced by the device. + additionalProperties: + type: object + additionalProperties: + type: object + title: OneTimeKeys + example: + "@alice:example.com": + JLAFKJWSCS: + signed_curve25519:AAAAHg: + key: zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs + signatures: + "@alice:example.com": + ed25519:JLAFKJWSCS: FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw + required: + - one_time_keys tags: - End-to-end encryption - "/keys/changes": + /keys/changes: get: summary: Query users with recent device key updates. description: |- @@ -439,48 +379,70 @@ paths: parameters: - in: query name: from - type: string description: |- - The desired start point of the list. Should be the `next_batch` field - from a response to an earlier call to [`/sync`](/client-server-api/#get_matrixclientv3sync). Users who have not - uploaded new device identity keys since this point, nor deleted - existing devices with identity keys since then, will be excluded - from the results. + The desired start point of the list. Should be the `next_batch` field + from a response to an earlier call to [`/sync`](/client-server-api/#get_matrixclientv3sync). Users who have not + uploaded new device identity keys since this point, nor deleted + existing devices with identity keys since then, will be excluded + from the results. required: true - x-example: "s72594_4483_1934" + example: s72594_4483_1934 + schema: + type: string - in: query name: to - type: string description: |- - The desired end point of the list. Should be the `next_batch` - field from a recent call to [`/sync`](/client-server-api/#get_matrixclientv3sync) - typically the most recent - such call. This may be used by the server as a hint to check its - caches are up to date. + The desired end point of the list. Should be the `next_batch` + field from a recent call to [`/sync`](/client-server-api/#get_matrixclientv3sync) - typically the most recent + such call. This may be used by the server as a hint to check its + caches are up to date. required: true - x-example: "s75689_5632_2435" - responses: - 200: - description: - The list of users who updated their devices. + example: s75689_5632_2435 schema: - type: object - properties: - changed: - type: array - items: - type: string - description: |- - The Matrix User IDs of all users who updated their device - identity keys. - example: ["@alice:example.com", "@bob:example.org"] - left: - type: array - items: - type: string - description: |- - The Matrix User IDs of all users who may have left all - the end-to-end encrypted rooms they previously shared - with the user. - example: ["@clara:example.com", "@doug:example.org"] + type: string + responses: + "200": + description: The list of users who updated their devices. + content: + application/json: + schema: + type: object + properties: + changed: + type: array + items: + type: string + description: |- + The Matrix User IDs of all users who updated their device + identity keys. + example: + - "@alice:example.com" + - "@bob:example.org" + left: + type: array + items: + type: string + description: |- + The Matrix User IDs of all users who may have left all + the end-to-end encrypted rooms they previously shared + with the user. + example: + - "@clara:example.com" + - "@doug:example.org" tags: - End-to-end encryption +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 diff --git a/data/api/client-server/kicking.yaml b/data/api/client-server/kicking.yaml index c0d8f6710..6eaa8243f 100644 --- a/data/api/client-server/kicking.yaml +++ b/data/api/client-server/kicking.yaml @@ -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 Room Kicking 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 Room Kicking API + version: 1.0.0 paths: "/rooms/{roomId}/kick": post: @@ -43,39 +32,44 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room identifier (not alias) from which the user should be kicked. required: true - x-example: "!e42d8c:matrix.org" - - in: body - name: body - required: true + example: "!e42d8c:matrix.org" schema: - type: object - example: { + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { "reason": "Telling unfunny jokes", "user_id": "@cheeky_monkey:matrix.org" } - properties: - user_id: - type: string - description: The fully qualified user ID of the user being kicked. - reason: - type: string - description: |- - The reason the user has been kicked. This will be supplied as the - `reason` on the target's updated [`m.room.member`](/client-server-api/#mroommember) event. - required: ["user_id"] + properties: + user_id: + type: string + description: The fully qualified user ID of the user being kicked. + reason: + type: string + description: |- + The reason the user has been kicked. This will be supplied as the + `reason` on the target's updated [`m.room.member`](/client-server-api/#mroommember) event. + required: + - user_id + required: true responses: - 200: + "200": description: The user has been kicked from the room. - examples: - application/json: { - } - schema: - type: object - 403: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "403": description: |- You do not have permission to kick the user from the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are: @@ -83,12 +77,30 @@ paths: - The kicker is not currently in the room. - The kickee is not currently in the room. - The kicker's power level is insufficient to kick users from the room. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "You do not have a high enough power level to kick from this room." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You do not have a high enough power level to kick from this room." + } tags: - Room membership +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 diff --git a/data/api/client-server/knocking.yaml b/data/api/client-server/knocking.yaml index c2a760ca6..f8f16b486 100644 --- a/data/api/client-server/knocking.yaml +++ b/data/api/client-server/knocking.yaml @@ -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 Room Knocking 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 Room Knocking API + version: 1.0.0 paths: "/knock/{roomIdOrAlias}": post: @@ -52,74 +41,109 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomIdOrAlias description: The room identifier or alias to knock upon. required: true - x-example: "#monkeys:matrix.org" - - in: query - type: array - items: + example: "#monkeys:matrix.org" + schema: type: string + - in: query name: server_name description: |- The servers to attempt to knock on the room through. One of the servers must be participating in the room. - x-example: ["matrix.org", "elsewhere.ca"] - - in: body - name: body - required: true + example: + - matrix.org + - elsewhere.ca + style: form + explode: false schema: - type: object - properties: - reason: - type: string - description: |- - Optional reason to be included as the `reason` on the subsequent - membership event. - example: "Looking for support" + type: array + items: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + reason: + type: string + description: |- + Optional reason to be included as the `reason` on the subsequent + membership event. + example: Looking for support + required: true responses: - 200: + "200": description: |- The room has been knocked upon. The knocked room ID must be returned in the `room_id` field. - examples: - application/json: { - "room_id": "!d41d8cd:matrix.org" - } - schema: - type: object - properties: - room_id: - type: string - description: The knocked room ID. - required: ["room_id"] - 403: + content: + application/json: + schema: + type: object + properties: + room_id: + type: string + description: The knocked room ID. + required: + - room_id + examples: + response: + value: { + "room_id": "!d41d8cd:matrix.org" + } + "403": description: |- You do not have permission to knock on the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejection are: - The room is not set up for knocking. - The user has been banned from the room. - examples: - application/json: { - "errcode": "M_FORBIDDEN", "error": "You are not allowed to knock on this room." - } - schema: - "$ref": "definitions/errors/error.yaml" - 404: - description: |- - The room could not be found or resolved to a room ID. - examples: - application/json: { - "errcode": "M_NOT_FOUND", "error": "That room does not appear to exist." - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You are not allowed to knock on this room." + } + "404": + description: The room could not be found or resolved to a room ID. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "That room does not appear to exist." + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Room membership +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 diff --git a/data/api/client-server/leaving.yaml b/data/api/client-server/leaving.yaml index ce304883d..6e7d67d01 100644 --- a/data/api/client-server/leaving.yaml +++ b/data/api/client-server/leaving.yaml @@ -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 Room Leaving 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 Room Leaving API + version: 1.0.0 paths: "/rooms/{roomId}/leave": post: @@ -47,39 +36,44 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room identifier to leave. required: true - x-example: "!nkl290a:matrix.org" - - in: body - name: body - required: true + example: "!nkl290a:matrix.org" schema: - type: object - example: { - "reason": "Saying farewell - thanks for the support!" - } - properties: - reason: - x-addedInMatrixVersion: "1.1" - type: string - description: |- - Optional reason to be included as the `reason` on the subsequent - membership event. - responses: - 200: - description: |- - The room has been left. - examples: - application/json: { + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { + "reason": "Saying farewell - thanks for the support!" } - schema: - type: object - 429: + properties: + reason: + x-addedInMatrixVersion: "1.1" + type: string + description: |- + Optional reason to be included as the `reason` on the subsequent + membership event. + required: true + responses: + "200": + description: The room has been left. + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Room membership "/rooms/{roomId}/forget": @@ -100,32 +94,54 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room identifier to forget. required: true - x-example: "!au1ba7o:matrix.org" - responses: - 200: - description: |- - The room has been forgotten. - examples: - application/json: { - } + example: "!au1ba7o:matrix.org" schema: - type: object - 400: + type: string + responses: + "200": + description: The room has been forgotten. + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "400": description: The user has not left the room - examples: - application/json: { - "errcode": "M_UNKNOWN", - "error": "User @example:matrix.org is in room !au1ba7o:matrix.org" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_UNKNOWN", + "error": "User @example:matrix.org is in room !au1ba7o:matrix.org" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Room membership +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 diff --git a/data/api/client-server/list_joined_rooms.yaml b/data/api/client-server/list_joined_rooms.yaml index 177949bff..68451409f 100644 --- a/data/api/client-server/list_joined_rooms.yaml +++ b/data/api/client-server/list_joined_rooms.yaml @@ -11,48 +11,54 @@ # 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 Room Listing 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 Room Listing API + version: 1.0.0 paths: - "/joined_rooms": + /joined_rooms: get: summary: Lists the user's current rooms. - description: |- - This API returns a list of the user's current rooms. + description: This API returns a list of the user's current rooms. operationId: getJoinedRooms security: - accessToken: [] responses: - 200: + "200": description: A list of the rooms the user is in. - schema: - type: object - required: ["joined_rooms"] - properties: - joined_rooms: - type: array - description: |- - The ID of each room in which the user has `joined` membership. - items: - type: string - examples: - application/json: { - "joined_rooms": [ - "!foo:example.com" - ] - } + content: + application/json: + schema: + type: object + required: + - joined_rooms + properties: + joined_rooms: + type: array + description: The ID of each room in which the user has `joined` membership. + items: + type: string + examples: + response: + value: { + "joined_rooms": [ + "!foo:example.com" + ] + } tags: - Room membership +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 diff --git a/data/api/client-server/list_public_rooms.yaml b/data/api/client-server/list_public_rooms.yaml index 185a955eb..e4f0551b8 100644 --- a/data/api/client-server/list_public_rooms.yaml +++ b/data/api/client-server/list_public_rooms.yaml @@ -11,56 +11,56 @@ # 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 Room Directory API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json + title: Matrix Client-Server Room Directory API + version: 1.0.0 paths: "/directory/list/room/{roomId}": get: summary: Gets the visibility of a room in the directory - description: |- - Gets the visibility of a given room on the server's public room directory. + description: Gets the visibility of a given room on the server's public room + directory. operationId: getRoomVisibilityOnDirectory parameters: - in: path - type: string name: roomId description: The room ID. required: true - x-example: "!curbf:matrix.org" + example: "!curbf:matrix.org" + schema: + type: string responses: - 200: + "200": description: The visibility of the room in the directory - schema: - type: object - properties: - visibility: - type: string - enum: ['private', 'public'] - description: The visibility of the room in the directory. - examples: - application/json: { - "visibility": "public" - } - 404: + content: + application/json: + schema: + type: object + properties: + visibility: + type: string + enum: + - private + - public + description: The visibility of the room in the directory. + examples: + response: + value: { + "visibility": "public" + } + "404": description: The room is not known to the server - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Room not found" - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Room not found" + } tags: - Room discovery put: @@ -77,47 +77,56 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room ID. required: true - x-example: "!curbf:matrix.org" - - in: body - name: body - required: true - description: |- - The new visibility for the room on the room directory. + example: "!curbf:matrix.org" schema: - type: object - properties: - visibility: - type: string - enum: ["private", "public"] - description: |- - The new visibility setting for the room. - Defaults to 'public'. - example: { - "visibility": "public" - } + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + visibility: + type: string + enum: + - private + - public + description: |- + The new visibility setting for the room. + Defaults to 'public'. + example: { + "visibility": "public" + } + description: The new visibility for the room on the room directory. + required: true responses: - 200: + "200": description: The visibility was updated, or no change was needed. - examples: - application/json: {} - schema: - type: object - 404: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "404": description: The room is not known to the server - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Room not found" - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Room not found" + } tags: - Room discovery - "/publicRooms": + /publicRooms: get: summary: Lists the public rooms on the server. description: |- @@ -129,28 +138,32 @@ paths: parameters: - in: query name: limit - type: integer - description: |- - Limit the number of results returned. + description: Limit the number of results returned. + schema: + type: integer - in: query name: since - type: string description: |- A pagination token from a previous request, allowing clients to get the next (or previous) batch of rooms. The direction of pagination is specified solely by which token is supplied, rather than via an explicit flag. + schema: + type: string - in: query name: server - type: string description: |- The server to fetch the public room lists from. Defaults to the local server. + schema: + type: string responses: - 200: + "200": description: A list of the rooms on the server. - schema: - $ref: "definitions/public_rooms_response.yaml" + content: + application/json: + schema: + $ref: definitions/public_rooms_response.yaml tags: - Room discovery post: @@ -166,35 +179,32 @@ paths: parameters: - in: query name: server - type: string description: |- The server to fetch the public room lists from. Defaults to the local server. - - in: body - name: body - required: true - description: |- - Options for which rooms to return. schema: - type: object - properties: - limit: - type: integer - description: |- - Limit the number of results returned. - since: - type: string - description: |- - A pagination token from a previous request, allowing clients - to get the next (or previous) batch of rooms. The direction - of pagination is specified solely by which token is supplied, - rather than via an explicit flag. - filter: - type: object - title: "Filter" - description: |- - Filter to apply to the results. - properties: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + limit: + type: integer + description: Limit the number of results returned. + since: + type: string + description: |- + A pagination token from a previous request, allowing clients + to get the next (or previous) batch of rooms. The direction + of pagination is specified solely by which token is supplied, + rather than via an explicit flag. + filter: + type: object + title: Filter + description: Filter to apply to the results. + properties: generic_search_term: type: string description: |- @@ -210,31 +220,50 @@ paths: for. To include rooms without a room type, specify `null` within this list. When not specified, all applicable rooms (regardless of type) are returned. - include_all_networks: - type: boolean - description: |- - Whether or not to include all known networks/protocols from - application services on the homeserver. Defaults to false. - example: false - third_party_instance_id: - type: string - description: |- - The specific third-party network/protocol to request from the - homeserver. Can only be used if `include_all_networks` is false. - example: "irc" - example: { - "limit": 10, - "filter": { - "generic_search_term": "foo", - "room_types": [null, "m.space"] - }, - "include_all_networks": false, - "third_party_instance_id": "irc" - } + include_all_networks: + type: boolean + description: |- + Whether or not to include all known networks/protocols from + application services on the homeserver. Defaults to false. + example: false + third_party_instance_id: + type: string + description: |- + The specific third-party network/protocol to request from the + homeserver. Can only be used if `include_all_networks` is false. + example: irc + example: { + "limit": 10, + "filter": { + "generic_search_term": "foo", + "room_types": [ + null, + "m.space" + ] + }, + "include_all_networks": false, + "third_party_instance_id": "irc" + } + description: Options for which rooms to return. + required: true responses: - 200: + "200": description: A list of the rooms on the server. - schema: - $ref: "definitions/public_rooms_response.yaml" + content: + application/json: + schema: + $ref: definitions/public_rooms_response.yaml tags: - Room discovery +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 diff --git a/data/api/client-server/login.yaml b/data/api/client-server/login.yaml index 7c33d1a4e..3bcc90aa6 100644 --- a/data/api/client-server/login.yaml +++ b/data/api/client-server/login.yaml @@ -13,23 +13,12 @@ # 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 Registration and Login 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 Registration and Login API + version: 1.0.0 paths: - "/login": + /login: get: summary: Get the supported login types to authenticate users description: |- @@ -37,33 +26,40 @@ paths: should pick one of these and supply it as the `type` when logging in. operationId: getLoginFlows responses: - 200: + "200": description: The login types the homeserver supports - examples: - application/json: { - "flows": [ - {"type": "m.login.password"} - ] - } - schema: - type: object - properties: - flows: - type: array - description: The homeserver's supported login types - items: - type: object - title: LoginFlow - properties: - type: - description: |- - The login type. This is supplied as the `type` when - logging in. - type: string - 429: + content: + application/json: + schema: + type: object + properties: + flows: + type: array + description: The homeserver's supported login types + items: + type: object + title: LoginFlow + properties: + type: + description: |- + The login type. This is supplied as the `type` when + logging in. + type: string + examples: + response: + value: { + "flows": [ + { + "type": "m.login.password" + } + ] + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Session management post: @@ -80,13 +76,12 @@ paths: invalidate any access token previously associated with that device. See [Relationship between access tokens and devices](/client-server-api/#relationship-between-access-tokens-and-devices). operationId: login - parameters: - - in: body - name: body - required: true - schema: - type: object - example: { + requestBody: + content: + application/json: + schema: + type: object + example: { "type": "m.login.password", "identifier": { "type": "m.id.user", @@ -95,148 +90,182 @@ paths: "password": "ilovebananas", "initial_device_display_name": "Jungle Phone" } - properties: - type: - type: string - enum: ["m.login.password", "m.login.token"] - description: The login type being used. - identifier: - "$ref": "definitions/user_identifier.yaml" - user: - type: string - description: The fully qualified user ID or just local part of the user ID, to log in. Deprecated in favour of `identifier`. - medium: - type: string - description: When logging in using a third-party identifier, the medium of the identifier. Must be 'email'. Deprecated in favour of `identifier`. - address: - type: string - description: Third-party identifier for the user. Deprecated in favour of `identifier`. - password: - type: string - description: |- - Required when `type` is `m.login.password`. The user's - password. - token: - type: string - description: |- - Required when `type` is `m.login.token`. Part of Token-based login. - device_id: - type: string - description: |- - ID of the client device. If this does not correspond to a - known client device, a new device will be created. The given - device ID must not be the same as a - [cross-signing](/client-server-api/#cross-signing) key ID. - The server will auto-generate a device_id - if this is not specified. - initial_device_display_name: - type: string - description: |- - A display name to assign to the newly-created device. Ignored - if `device_id` corresponds to a known device. - refresh_token: - type: boolean - description: |- - If true, the client supports refresh tokens. - x-addedInMatrixVersion: "1.3" - required: ["type"] - + properties: + type: + type: string + enum: + - m.login.password + - m.login.token + description: The login type being used. + identifier: + $ref: definitions/user_identifier.yaml + user: + type: string + description: The fully qualified user ID or just local part of the user ID, to + log in. Deprecated in favour of `identifier`. + medium: + type: string + description: When logging in using a third-party identifier, the medium of the + identifier. Must be 'email'. Deprecated in favour of + `identifier`. + address: + type: string + description: Third-party identifier for the user. Deprecated in favour of + `identifier`. + password: + type: string + description: |- + Required when `type` is `m.login.password`. The user's + password. + token: + type: string + description: Required when `type` is `m.login.token`. Part of Token-based login. + device_id: + type: string + description: |- + ID of the client device. If this does not correspond to a + known client device, a new device will be created. The given + device ID must not be the same as a + [cross-signing](/client-server-api/#cross-signing) key ID. + The server will auto-generate a device_id + if this is not specified. + initial_device_display_name: + type: string + description: |- + A display name to assign to the newly-created device. Ignored + if `device_id` corresponds to a known device. + refresh_token: + type: boolean + description: If true, the client supports refresh tokens. + x-addedInMatrixVersion: "1.3" + required: + - type + required: true responses: - 200: + "200": description: The user has been authenticated. - examples: - application/json: { - "user_id": "@cheeky_monkey:matrix.org", - "access_token": "abc123", - "refresh_token": "def456", - "expires_in_ms": 60000, - "device_id": "GHTYAJCE", - "well_known": { - "m.homeserver": { - "base_url": "https://example.org" - }, - "m.identity_server": { - "base_url": "https://id.example.org" - } - } - } - schema: - type: object - properties: - user_id: - type: string - description: The fully-qualified Matrix ID for the account. - access_token: - type: string - description: |- - An access token for the account. - This access token can then be used to authorize other requests. - refresh_token: - type: string - description: |- - A refresh token for the account. This token can be used to - obtain a new access token when it expires by calling the - `/refresh` endpoint. - x-addedInMatrixVersion: "1.3" - expires_in_ms: - type: integer - description: |- - The lifetime of the access token, in milliseconds. Once - the access token has expired a new access token can be - obtained by using the provided refresh token. If no - refresh token is provided, the client will need to re-log in - to obtain a new access token. If not given, the client can - assume that the access token will not expire. - x-addedInMatrixVersion: "1.3" - home_server: - type: string - description: |- - The server_name of the homeserver on which the account has - been registered. + content: + application/json: + schema: + type: object + properties: + user_id: + type: string + description: The fully-qualified Matrix ID for the account. + access_token: + type: string + description: |- + An access token for the account. + This access token can then be used to authorize other requests. + refresh_token: + type: string + description: |- + A refresh token for the account. This token can be used to + obtain a new access token when it expires by calling the + `/refresh` endpoint. + x-addedInMatrixVersion: "1.3" + expires_in_ms: + type: integer + description: |- + The lifetime of the access token, in milliseconds. Once + the access token has expired a new access token can be + obtained by using the provided refresh token. If no + refresh token is provided, the client will need to re-log in + to obtain a new access token. If not given, the client can + assume that the access token will not expire. + x-addedInMatrixVersion: "1.3" + home_server: + type: string + description: |- + The server_name of the homeserver on which the account has + been registered. - **Deprecated**. Clients should extract the server_name from - `user_id` (by splitting at the first colon) if they require - it. Note also that `homeserver` is not spelt this way. - device_id: - type: string - description: |- - ID of the logged-in device. Will be the same as the - corresponding parameter in the request, if one was specified. - well_known: - description: |- - Optional client configuration provided by the server. If present, - clients SHOULD use the provided object to reconfigure themselves, - optionally validating the URLs within. This object takes the same - form as the one returned from .well-known autodiscovery. - allOf: - - "$ref": "definitions/wellknown/full.yaml" - required: ["access_token", "device_id", "user_id"] - 400: - description: |- - Part of the request was invalid. For example, the login type may not be recognised. - examples: - application/json: { - "errcode": "M_UNKNOWN", - "error": "Bad login type." - } - schema: - "$ref": "definitions/errors/error.yaml" - 403: + **Deprecated**. Clients should extract the server_name from + `user_id` (by splitting at the first colon) if they require + it. Note also that `homeserver` is not spelt this way. + device_id: + type: string + description: |- + ID of the logged-in device. Will be the same as the + corresponding parameter in the request, if one was specified. + well_known: + description: |- + Optional client configuration provided by the server. If present, + clients SHOULD use the provided object to reconfigure themselves, + optionally validating the URLs within. This object takes the same + form as the one returned from .well-known autodiscovery. + allOf: + - $ref: definitions/wellknown/full.yaml + required: + - access_token + - device_id + - user_id + examples: + response: + value: { + "user_id": "@cheeky_monkey:matrix.org", + "access_token": "abc123", + "refresh_token": "def456", + "expires_in_ms": 60000, + "device_id": "GHTYAJCE", + "well_known": { + "m.homeserver": { + "base_url": "https://example.org" + }, + "m.identity_server": { + "base_url": "https://id.example.org" + } + } + } + "400": + description: Part of the request was invalid. For example, the login type may + not be recognised. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_UNKNOWN", + "error": "Bad login type." + } + "403": description: |- The login attempt failed. This can include one of the following error codes: * `M_FORBIDDEN`: The provided authentication data was incorrect or the requested device ID is the same as a cross-signing key ID. * `M_USER_DEACTIVATED`: The user has been deactivated. - examples: - application/json: { - "errcode": "M_FORBIDDEN" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Session management +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 diff --git a/data/api/client-server/logout.yaml b/data/api/client-server/logout.yaml index ad809de05..c3287472f 100644 --- a/data/api/client-server/logout.yaml +++ b/data/api/client-server/logout.yaml @@ -11,23 +11,12 @@ # 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 Registration and Login 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 Registration and Login API + version: 1.0.0 paths: - "/logout": + /logout: post: summary: Invalidates a user access token description: |- @@ -38,14 +27,16 @@ paths: security: - accessToken: [] responses: - 200: + "200": description: The access token used in the request was successfully invalidated. - schema: - type: object - properties: {} + content: + application/json: + schema: + type: object + properties: {} tags: - Session management - "/logout/all": + /logout/all: post: summary: Invalidates all access tokens for a user description: |- @@ -64,10 +55,27 @@ paths: security: - accessToken: [] responses: - 200: + "200": description: The user's access tokens were successfully invalidated. - schema: - type: object - properties: {} + content: + application/json: + schema: + type: object + properties: {} tags: - Session management +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 diff --git a/data/api/client-server/message_pagination.yaml b/data/api/client-server/message_pagination.yaml index cc4d72b41..940b98027 100644 --- a/data/api/client-server/message_pagination.yaml +++ b/data/api/client-server/message_pagination.yaml @@ -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" + example: b + schema: + type: string + enum: + - b + - f - in: query - type: integer name: limit - description: |- - The maximum number of events to return. Default: 10. - x-example: "3" + description: "The maximum number of events to return. Default: 10." + example: "3" + schema: + type: integer - in: query - type: string name: filter - description: |- - A JSON RoomEventFilter to filter returned events with. - x-example: |- - {"contains_url":true} + description: A JSON RoomEventFilter to filter returned events with. + example: '{"contains_url":true}' + schema: + type: string responses: - 200: + "200": description: A list of messages with a new token to request more. - 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. + content: + application/json: + 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.) + 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`. + 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: - 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: > + 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 diff --git a/data/api/client-server/notifications.yaml b/data/api/client-server/notifications.yaml index 8f8b62b41..1cde576bc 100644 --- a/data/api/client-server/notifications.yaml +++ b/data/api/client-server/notifications.yaml @@ -11,24 +11,12 @@ # 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 Notifications 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 Notifications API + version: 1.0.0 paths: - "/notifications": + /notifications: get: summary: Gets a list of events that the user has been notified about description: |- @@ -39,97 +27,124 @@ paths: - accessToken: [] parameters: - in: query - type: string name: from description: |- Pagination token to continue from. This should be the `next_token` returned from an earlier call to this endpoint. required: false - x-example: "xxxxx" + example: xxxxx + schema: + type: string - in: query - type: integer name: limit description: Limit on the number of events to return in this request. required: false - x-example: 20 + example: 20 + schema: + type: integer - in: query name: only - type: string description: |- Allows basic filtering of events returned. Supply `highlight` to return only events where the notification had the highlight tweak set. required: false - x-example: "highlight" + example: highlight + schema: + type: string responses: - 200: + "200": description: A batch of events is being returned - examples: - application/json: { - "next_token": "abcdef", - "notifications": [ - { - "actions": [ - "notify" - ], - "profile_tag": "hcbvkzxhcvb", - "read": true, - "room_id": "!abcdefg:example.com", - "ts": 1475508881945, - "event": { - "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" - } + content: + application/json: + schema: + type: object + required: + - notifications + properties: + next_token: + type: string + description: |- + The token to supply in the `from` param of the next + `/notifications` request in order to request more + events. If this is absent, there are no more results. + notifications: + type: array + items: + type: object + required: + - actions + - event + - read + - room_id + - ts + title: Notification + properties: + actions: + type: array + description: |- + The action(s) to perform when the conditions for this rule are met. + See [Push Rules: API](/client-server-api/#push-rules-api). + items: + oneOf: + - type: object + - type: string + event: + title: Event + description: The Event object for the event that triggered the notification. + allOf: + - $ref: definitions/client_event_without_room_id.yaml + profile_tag: + type: string + description: The profile tag of the rule that matched this event. + read: + type: boolean + description: |- + Indicates whether the user has sent a read receipt indicating + that they have read this message. + room_id: + type: string + description: The ID of the room in which the event was posted. + ts: + type: integer + format: int64 + description: |- + The unix timestamp at which the event notification was sent, + in milliseconds. + description: The list of events that triggered notifications. + examples: + response: + value: { + "next_token": "abcdef", + "notifications": [ + { + "actions": [ + "notify" + ], + "profile_tag": "hcbvkzxhcvb", + "read": true, + "room_id": "!abcdefg:example.com", + "ts": 1475508881945, + "event": { + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + } + } + ] } - ] - } - schema: - type: object - required: ["notifications"] - properties: - next_token: - type: string - description: |- - The token to supply in the `from` param of the next - `/notifications` request in order to request more - events. If this is absent, there are no more results. - notifications: - type: array - items: - type: object - required: ["actions", "event", "read", "room_id", "ts"] - title: Notification - properties: - actions: - type: array - description: |- - The action(s) to perform when the conditions for this rule are met. - See [Push Rules: API](/client-server-api/#push-rules-api). - items: - type: - - object - - string - event: - title: Event - description: The Event object for the event that triggered the notification. - allOf: - - "$ref": "definitions/client_event_without_room_id.yaml" - profile_tag: - type: string - description: The profile tag of the rule that matched this event. - read: - type: boolean - description: |- - Indicates whether the user has sent a read receipt indicating - that they have read this message. - room_id: - type: string - description: The ID of the room in which the event was posted. - ts: - type: integer - format: int64 - description: |- - The unix timestamp at which the event notification was sent, - in milliseconds. - description: The list of events that triggered notifications. tags: - Push notifications +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 diff --git a/data/api/client-server/old_sync.yaml b/data/api/client-server/old_sync.yaml index 329289d8e..3e0ad0b65 100644 --- a/data/api/client-server/old_sync.yaml +++ b/data/api/client-server/old_sync.yaml @@ -11,23 +11,12 @@ # 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 Sync 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 Sync API + version: 1.0.0 paths: - "/events": + /events: get: summary: Listen on the event stream. description: |- @@ -43,54 +32,61 @@ paths: - accessToken: [] parameters: - in: query - type: string name: from description: |- The token to stream from. This token is either from a previous request to this API or from the initial sync API. required: false - x-example: "s3456_9_0" + example: s3456_9_0 + schema: + type: string - in: query - type: integer name: timeout description: The maximum time in milliseconds to wait for an event. required: false - x-example: "35000" - responses: - 200: - description: "The events received, which may be none." - examples: - application/json: { - "start": "s3456_9_0", - "end": "s3457_9_0", - "chunk": [ - {"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"} - ] - } + example: "35000" schema: - type: object - properties: - start: - type: string - description: |- - A token which correlates to the start of `chunk`. This - is usually the same token supplied to `from=`. - end: - type: string - description: |- - A token which correlates to the end of `chunk`. This - token should be used in the next request to `/events`. - chunk: - type: array - description: "An array of events." - items: - $ref: "definitions/client_event.yaml" - 400: - description: "Bad pagination `from` parameter." + type: integer + responses: + "200": + description: The events received, which may be none. + content: + application/json: + schema: + type: object + properties: + start: + type: string + description: |- + A token which correlates to the start of `chunk`. This + is usually the same token supplied to `from=`. + end: + type: string + description: |- + A token which correlates to the end of `chunk`. This + token should be used in the next request to `/events`. + chunk: + type: array + description: An array of events. + items: + $ref: definitions/client_event.yaml + examples: + response: + value: { + "start": "s3456_9_0", + "end": "s3457_9_0", + "chunk": [ + { + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + } + ] + } + "400": + description: Bad pagination `from` parameter. tags: - Room participation deprecated: true - "/initialSync": + /initialSync: get: summary: Get the user's current state. description: |- @@ -106,13 +102,13 @@ paths: - accessToken: [] parameters: - in: query - type: integer name: limit description: The maximum number of messages to return for each room. required: false - x-example: "2" + example: "2" + schema: + type: integer - in: query - type: boolean name: archived description: |- Whether to include rooms that the user has left. If `false` then @@ -120,176 +116,201 @@ paths: included. If set to `true` then rooms that the user has left are included as well. By default this is `false`. required: false - x-example: "true" + example: "true" + schema: + type: boolean responses: - 200: + "200": description: The user's current state. - examples: - application/json: { - "end": "s3456_9_0", - "presence": [ - {"$ref": "../../event-schemas/examples/m.presence.yaml"} - ], - "account_data": [ - { - "type": "org.example.custom.config", - "content": { - "custom_config_key": "custom_config_value" - } - } - ], - "rooms": [ - { - "membership": "join", - "messages": { - "chunk": [ - { - "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", - "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" - }, - { - "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", - "$ref": "../../event-schemas/examples/m.room.message$m.video.yaml" - } - ], - "end": "s3456_9_0", - "start": "t44-3453_9_0" - }, - "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", - "state": [ - { - "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", - "$ref": "../../event-schemas/examples/m.room.join_rules.yaml" - }, - { - "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", - "$ref": "../../event-schemas/examples/m.room.member.yaml" - }, - { - "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", - "$ref": "../../event-schemas/examples/m.room.create.yaml" - }, - { - "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", - "$ref": "../../event-schemas/examples/m.room.power_levels.yaml" - } - ], - "visibility": "private", - "account_data": [ - { - "type": "m.tag", - "content": {"tags": {"work": {"order": 1}}} - }, - { - "type": "org.example.custom.room.config", - "content": { - "custom_config_key": "custom_config_value" - } - } - ] - } - ] - } - schema: - type: object - properties: - end: - type: string - description: |- - A token which correlates to the end of the timelines returned. This - token should be used with the `/events` endpoint to listen for new - events. - presence: - type: array - description: A list of presence events. - items: - $ref: "definitions/client_event.yaml" - rooms: - type: array - items: - type: object - title: RoomInfo - properties: - room_id: - type: string - description: "The ID of this room." - membership: - type: string - description: "The user's membership state in this room." - enum: ["invite", "join", "leave", "ban"] - invite: - type: object - title: "InviteEvent" - description: "The invite event if `membership` is `invite`" - allOf: - - $ref: "definitions/client_event.yaml" - messages: + content: + application/json: + schema: + type: object + properties: + end: + type: string + description: |- + A token which correlates to the end of the timelines returned. This + token should be used with the `/events` endpoint to listen for new + events. + presence: + type: array + description: A list of presence events. + items: + $ref: definitions/client_event.yaml + rooms: + type: array + items: type: object - title: PaginationChunk - description: "The pagination chunk for this room." + title: RoomInfo properties: - start: + room_id: type: string - description: |- - A token which correlates to the start of `chunk`. - Can be passed to - [`/rooms//messages`](#get_matrixclientv3roomsroomidmessages) - to retrieve earlier events. + description: The ID of this room. + membership: + type: string + description: The user's membership state in this room. + enum: + - invite + - join + - leave + - ban + invite: + type: object + title: InviteEvent + description: The invite event if `membership` is `invite` + allOf: + - $ref: definitions/client_event.yaml + messages: + type: object + title: PaginationChunk + description: The pagination chunk for this room. + properties: + start: + type: string + description: |- + A token which correlates to the start of `chunk`. + Can be passed to + [`/rooms//messages`](#get_matrixclientv3roomsroomidmessages) + to retrieve earlier events. - If no earlier events are available, this property may be omitted from - the response. - end: + If no earlier events are available, this property may be omitted from + the response. + end: + type: string + description: |- + A token which correlates to the end of `chunk`. + Can be passed to + [`/rooms//messages`](#get_matrixclientv3roomsroomidmessages) + to retrieve later events. + chunk: + type: array + description: |- + If the user is a member of the room this will be a + list of the most recent messages for this room. If + the user has left the room this will be the + messages that preceded them leaving. This array + will consist of at most `limit` elements. + items: + $ref: definitions/client_event.yaml + required: + - end + - chunk + state: + type: array + description: |- + If the user is a member of the room this will be the + current state of the room as a list of events. If the + user has left the room this will be the state of the + room when they left it. + items: + $ref: definitions/client_event.yaml + visibility: type: string + enum: + - private + - public description: |- - A token which correlates to the end of `chunk`. - Can be passed to - [`/rooms//messages`](#get_matrixclientv3roomsroomidmessages) - to retrieve later events. - chunk: + Whether this room is visible to the `/publicRooms` API + or not." + account_data: type: array description: |- - If the user is a member of the room this will be a - list of the most recent messages for this room. If - the user has left the room this will be the - messages that preceded them leaving. This array - will consist of at most `limit` elements. + The private data that this user has attached to + this room. items: - $ref: "definitions/client_event.yaml" - required: ["end", "chunk"] - state: - type: array - description: |- - If the user is a member of the room this will be the - current state of the room as a list of events. If the - user has left the room this will be the state of the - room when they left it. - items: - $ref: "definitions/client_event.yaml" - visibility: - type: string - enum: ["private", "public"] - description: |- - Whether this room is visible to the `/publicRooms` API - or not." - account_data: - type: array - description: |- - The private data that this user has attached to - this room. - items: - $ref: "definitions/client_event.yaml" - required: ["room_id", "membership"] - account_data: - type: array - description: |- - The global private data created by this user. - items: - title: Event - type: object - allOf: - - "$ref": "../../event-schemas/schema/core-event-schema/event.yaml" - required: ["end", "rooms", "presence"] - 404: + $ref: definitions/client_event.yaml + required: + - room_id + - membership + account_data: + type: array + description: The global private data created by this user. + items: + title: Event + type: object + allOf: + - $ref: ../../event-schemas/schema/core-event-schema/event.yaml + required: + - end + - rooms + - presence + examples: + response: + value: { + "end": "s3456_9_0", + "presence": [ + { + "$ref": "../../event-schemas/examples/m.presence.yaml" + } + ], + "account_data": [ + { + "type": "org.example.custom.config", + "content": { + "custom_config_key": "custom_config_value" + } + } + ], + "rooms": [ + { + "membership": "join", + "messages": { + "chunk": [ + { + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + }, + { + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "$ref": "../../event-schemas/examples/m.room.message$m.video.yaml" + } + ], + "end": "s3456_9_0", + "start": "t44-3453_9_0" + }, + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "state": [ + { + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "$ref": "../../event-schemas/examples/m.room.join_rules.yaml" + }, + { + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "$ref": "../../event-schemas/examples/m.room.member.yaml" + }, + { + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "$ref": "../../event-schemas/examples/m.room.create.yaml" + }, + { + "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", + "$ref": "../../event-schemas/examples/m.room.power_levels.yaml" + } + ], + "visibility": "private", + "account_data": [ + { + "type": "m.tag", + "content": { + "tags": { + "work": { + "order": 1 + } + } + } + }, + { + "type": "org.example.custom.room.config", + "content": { + "custom_config_key": "custom_config_value" + } + } + ] + } + ] + } + "404": description: There is no avatar URL for this user or this user does not exist. tags: - Room participation @@ -310,20 +331,42 @@ paths: - accessToken: [] parameters: - in: path - type: string name: eventId description: The event ID to get. required: true - x-example: "$asfDuShaf7Gafaw:matrix.org" + example: $asfDuShaf7Gafaw:matrix.org + schema: + type: string responses: - 200: + "200": description: The full event. - examples: - application/json: {"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"} - schema: - $ref: "definitions/client_event.yaml" - 404: - description: The event was not found or you do not have permission to read this event. + content: + application/json: + schema: + $ref: definitions/client_event.yaml + examples: + response: + value: { + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + } + "404": + description: The event was not found or you do not have permission to read this + event. tags: - Room participation deprecated: true +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 diff --git a/data/api/client-server/openid.yaml b/data/api/client-server/openid.yaml index 28c285169..2dbd1227d 100644 --- a/data/api/client-server/openid.yaml +++ b/data/api/client-server/openid.yaml @@ -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 OpenID 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 OpenID API + version: 1.0.0 paths: "/user/{userId}/openid/request_token": post: @@ -44,40 +33,62 @@ paths: - accessToken: [] parameters: - in: path - type: string name: userId description: |- The user to request an OpenID token for. Should be the user who is authenticated for the request. required: true - x-example: "@alice:example.com" - - in: body - name: body - description: An empty object. Reserved for future expansion. - required: true + example: "@alice:example.com" schema: - type: object - example: {} + type: string + requestBody: + content: + application/json: + schema: + type: object + example: {} + description: An empty object. Reserved for future expansion. + required: true responses: - 200: + "200": description: |- OpenID token information. This response is nearly compatible with the response documented in the [OpenID Connect 1.0 Specification](http://openid.net/specs/openid-connect-core-1_0.html#TokenResponse) with the only difference being the lack of an `id_token`. Instead, the Matrix homeserver's name is provided. - examples: - application/json: { - "access_token": "SomeT0kenHere", - "token_type": "Bearer", - "matrix_server_name": "example.com", - "expires_in": 3600, - } - schema: - $ref: "definitions/openid_token.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/openid_token.yaml + examples: + response: + value: { + "access_token": "SomeT0kenHere", + "token_type": "Bearer", + "matrix_server_name": "example.com", + "expires_in": 3600 + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - OpenID +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 diff --git a/data/api/client-server/peeking_events.yaml b/data/api/client-server/peeking_events.yaml index 4b8a6a96e..6ed44b790 100644 --- a/data/api/client-server/peeking_events.yaml +++ b/data/api/client-server/peeking_events.yaml @@ -11,24 +11,11 @@ # 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 Sync Guest 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 Sync Guest API + version: 1.0.0 paths: - # With an extra " " to disambiguate from the getEvents endpoint - # The extra space makes it sort first for what I'm sure is a good reason. "/events ": get: summary: Listen on the event stream of a particular room. @@ -48,62 +35,82 @@ paths: - accessToken: [] parameters: - in: query - type: string name: from description: |- The token to stream from. This token is either from a previous request to this API or from the initial sync API. required: false - x-example: "s3456_9_0" + example: s3456_9_0 + schema: + type: string - in: query - type: integer name: timeout description: The maximum time in milliseconds to wait for an event. required: false - x-example: "35000" + example: "35000" + schema: + type: integer - in: query - type: string name: room_id - description: |- - The room ID for which events should be returned. - x-example: + description: The room ID for which events should be returned. + example: - "!somewhere:over.the.rainbow" + schema: + type: string responses: - 200: - description: "The events received, which may be none." - examples: - application/json: { - "start": "s3456_9_0", - "end": "s3457_9_0", - "chunk": [ - { - "room_id": "!somewhere:over.the.rainbow", - "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + "200": + description: The events received, which may be none. + content: + application/json: + schema: + type: object + properties: + start: + type: string + description: |- + A token which correlates to the first value in `chunk`. This + is usually the same token supplied to `from=`. + end: + type: string + description: |- + A token which correlates to the last value in `chunk`. This + token should be used in the next request to `/events`. + chunk: + type: array + description: An array of events. + items: + type: object + title: Event + allOf: + - $ref: definitions/client_event.yaml + examples: + response: + value: { + "start": "s3456_9_0", + "end": "s3457_9_0", + "chunk": [ + { + "room_id": "!somewhere:over.the.rainbow", + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + } + ] } - ] - } - schema: - type: object - properties: - start: - type: string - description: |- - A token which correlates to the first value in `chunk`. This - is usually the same token supplied to `from=`. - end: - type: string - description: |- - A token which correlates to the last value in `chunk`. This - token should be used in the next request to `/events`. - chunk: - type: array - description: "An array of events." - items: - type: object - title: Event - allOf: - - "$ref": "definitions/client_event.yaml" - 400: - description: "Bad pagination `from` parameter." + "400": + description: Bad pagination `from` parameter. 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 diff --git a/data/api/client-server/presence.yaml b/data/api/client-server/presence.yaml index 6d144db29..4deda9e03 100644 --- a/data/api/client-server/presence.yaml +++ b/data/api/client-server/presence.yaml @@ -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 Presence 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 Presence API + version: 1.0.0 paths: "/presence/{userId}/status": put: @@ -40,99 +29,137 @@ paths: - accessToken: [] parameters: - in: path - type: string name: userId description: The user whose presence state to update. required: true - x-example: "@alice:example.com" - - in: body - name: presenceState - description: The updated presence state. - required: true + example: "@alice:example.com" schema: - type: object - example: { + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { "presence": "online", "status_msg": "I am here." } - properties: - presence: - type: string - enum: ["online", "offline", "unavailable"] - description: The new presence state. - status_msg: - type: string - description: The status message to attach to this state. - required: ["presence"] + properties: + presence: + type: string + enum: + - online + - offline + - unavailable + description: The new presence state. + status_msg: + type: string + description: The status message to attach to this state. + required: + - presence + description: The updated presence state. + required: true responses: - 200: + "200": description: The new presence state was set. - examples: - application/json: { - } - schema: - type: object # empty json object - 429: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Presence get: summary: Get this user's presence state. - description: |- - Get the given user's presence state. + description: Get the given user's presence state. operationId: getPresence security: - accessToken: [] parameters: - in: path - type: string name: userId description: The user whose presence state to get. required: true - x-example: "@alice:example.com" + example: "@alice:example.com" + schema: + type: string responses: - 200: + "200": description: The presence state for this user. - examples: - application/json: { - "presence": "unavailable", - "last_active_ago": 420845 - } - schema: - type: object - properties: - presence: - type: string - enum: ["online", "offline", "unavailable"] - description: This user's presence. - last_active_ago: - type: integer - description: |- - The length of time in milliseconds since an action was performed - by this user. - status_msg: - type: [string, "null"] - description: The state message for this user if one was set. - currently_active: - type: boolean - description: "Whether the user is currently active" - required: ["presence"] - 404: + content: + application/json: + schema: + type: object + properties: + presence: + type: string + enum: + - online + - offline + - unavailable + description: This user's presence. + last_active_ago: + type: integer + description: |- + The length of time in milliseconds since an action was performed + by this user. + status_msg: + description: The state message for this user if one was set. + nullable: true + type: string + currently_active: + type: boolean + description: Whether the user is currently active + required: + - presence + examples: + response: + value: { + "presence": "unavailable", + "last_active_ago": 420845 + } + "403": + description: You are not allowed to see this user's presence status. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You are not allowed to see their presence" + } + "404": description: |- There is no presence state for this user. This user may not exist or isn't exposing presence information to you. - schema: - "$ref": "definitions/errors/error.yaml" - 403: - description: You are not allowed to see this user's presence status. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "You are not allowed to see their presence" - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml tags: - Presence +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 diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml index 9865e0205..17d0d1b9b 100644 --- a/data/api/client-server/profile.yaml +++ b/data/api/client-server/profile.yaml @@ -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 Profile 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 Profile API + version: 1.0.0 paths: "/profile/{userId}/displayname": put: @@ -38,36 +27,42 @@ paths: - 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 new display name information. - required: true + example: "@alice:example.com" schema: - type: object - example: { + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { "displayname": "Alice Margatroid" } - properties: - displayname: - type: string - description: The new display name for this user. + properties: + displayname: + type: string + description: The new display name for this user. + description: The new display name information. + required: true responses: - 200: + "200": description: The display name was set. - examples: - application/json: { - } - schema: - type: object # empty json object - 429: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - User data get: @@ -79,25 +74,30 @@ paths: operationId: getDisplayName parameters: - in: path - type: string name: userId description: The user whose display name to get. required: true - x-example: "@alice:example.com" + example: "@alice:example.com" + schema: + type: string responses: - 200: + "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: + content: + application/json: + schema: + type: object + properties: + displayname: + type: string + description: The user's display name if they have set one, otherwise not + present. + examples: + response: + value: { + "displayname": "Alice Margatroid" + } + "404": description: There is no display name for this user or this user does not exist. tags: - User data @@ -112,37 +112,43 @@ paths: - 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 new avatar information. - required: true + example: "@alice:example.com" schema: - type: object - example: { + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { "avatar_url": "mxc://matrix.org/wefh34uihSDRGhw34" } - properties: - avatar_url: - type: string - format: uri - description: The new avatar URL for this user. + properties: + avatar_url: + type: string + format: uri + description: The new avatar URL for this user. + description: The new avatar information. + required: true responses: - 200: + "200": description: The avatar URL was set. - examples: - application/json: { - } - schema: - type: object # empty json object - 429: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - User data get: @@ -154,26 +160,30 @@ paths: operationId: getAvatarUrl parameters: - in: path - type: string name: userId description: The user whose avatar URL to get. required: true - x-example: "@alice:example.com" + example: "@alice:example.com" + schema: + type: string responses: - 200: + "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 - format: uri - description: The user's avatar URL if they have set one, otherwise not present. - 404: + content: + application/json: + schema: + type: object + properties: + avatar_url: + type: string + format: uri + description: The user's avatar URL if they have set one, otherwise not present. + examples: + response: + value: { + "avatar_url": "mxc://matrix.org/SDGdghriugerRg" + } + "404": description: There is no avatar URL for this user or this user does not exist. tags: - User data @@ -188,47 +198,75 @@ paths: operationId: getUserProfile parameters: - in: path - type: string name: userId description: The user whose profile information to get. required: true - x-example: "@alice:example.com" + example: "@alice:example.com" + schema: + type: string responses: - 200: + "200": description: The profile information for this user. - examples: - application/json: { - "avatar_url": "mxc://matrix.org/SDGdghriugerRg", - "displayname": "Alice Margatroid" - } - schema: - type: object - properties: - avatar_url: - type: string - format: uri - 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. - 403: + content: + application/json: + schema: + type: object + properties: + avatar_url: + type: string + format: uri + 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. + examples: + response: + value: { + "avatar_url": "mxc://matrix.org/SDGdghriugerRg", + "displayname": "Alice Margatroid" + } + "403": x-addedInMatrixVersion: "1.2" - description: The server is unwilling to disclose whether the user exists and/or has profile information. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "Profile lookup over federation is disabled on this homeserver" - } - schema: - "$ref": "definitions/errors/error.yaml" - 404: - description: There is no profile information for this user or this user does not exist. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Profile not found" - } - schema: - "$ref": "definitions/errors/error.yaml" + description: The server is unwilling to disclose whether the user exists and/or + has profile information. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "Profile lookup over federation is disabled on this homeserver" + } + "404": + description: There is no profile information for this user or this user does not + exist. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Profile not found" + } tags: - User data +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 diff --git a/data/api/client-server/pusher.yaml b/data/api/client-server/pusher.yaml index b797bb5ab..101104754 100644 --- a/data/api/client-server/pusher.yaml +++ b/data/api/client-server/pusher.yaml @@ -12,127 +12,117 @@ # 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 Push 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 Push API + version: 1.0.0 paths: - "/pushers": + /pushers: get: summary: Gets the current pushers for the authenticated user - description: |- - Gets all currently active pushers for the authenticated user. + description: Gets all currently active pushers for the authenticated user. operationId: getPushers security: - accessToken: [] responses: - 200: + "200": description: The pushers for this user. - examples: - application/json: { - "pushers": [ - { - "pushkey": "Xp/MzCt8/9DcSNE9cuiaoT5Ac55job3TdLSSmtmYl4A=", - "kind": "http", - "app_id": "face.mcapp.appy.prod", - "app_display_name": "Appy McAppface", - "device_display_name": "Alice's Phone", - "profile_tag": "xyz", - "lang": "en-US", - "data": { - "url": "https://example.com/_matrix/push/v1/notify" - } - } - ] - } - schema: - type: object - properties: - pushers: - type: array - title: Pushers - description: |- - An array containing the current pushers for the user - items: - type: object - title: Pusher - properties: - pushkey: - type: string - description: |- - This is a unique identifier for this pusher. See `/set` for - more detail. - Max length, 512 bytes. - kind: - type: string - description: |- - The kind of pusher. `"http"` is a pusher that - sends HTTP pokes. - app_id: - type: string - description: |- - This is a reverse-DNS style identifier for the application. - Max length, 64 chars. - app_display_name: - type: string - description: |- - A string that will allow the user to identify what application - owns this pusher. - device_display_name: - type: string - description: |- - A string that will allow the user to identify what device owns - this pusher. - profile_tag: - type: string - description: |- - This string determines which set of device specific rules this - pusher executes. - lang: - type: string - description: |- - The preferred language for receiving notifications (e.g. 'en' - or 'en-US') - data: + content: + application/json: + schema: + type: object + properties: + pushers: + type: array + title: Pushers + description: An array containing the current pushers for the user + items: type: object - description: |- - A dictionary of information for the pusher implementation - itself. - title: PusherData + title: Pusher properties: - url: + pushkey: type: string - format: uri description: |- - Required if `kind` is `http`. The URL to use to send - notifications to. - format: + This is a unique identifier for this pusher. See `/set` for + more detail. + Max length, 512 bytes. + kind: type: string description: |- - The format to use when sending notifications to the Push - Gateway. - required: - - pushkey - - app_id - - kind - - app_display_name - - device_display_name - - lang - - data + The kind of pusher. `"http"` is a pusher that + sends HTTP pokes. + app_id: + type: string + description: |- + This is a reverse-DNS style identifier for the application. + Max length, 64 chars. + app_display_name: + type: string + description: |- + A string that will allow the user to identify what application + owns this pusher. + device_display_name: + type: string + description: |- + A string that will allow the user to identify what device owns + this pusher. + profile_tag: + type: string + description: |- + This string determines which set of device specific rules this + pusher executes. + lang: + type: string + description: |- + The preferred language for receiving notifications (e.g. 'en' + or 'en-US') + data: + type: object + description: |- + A dictionary of information for the pusher implementation + itself. + title: PusherData + properties: + url: + type: string + format: uri + description: |- + Required if `kind` is `http`. The URL to use to send + notifications to. + format: + type: string + description: |- + The format to use when sending notifications to the Push + Gateway. + required: + - pushkey + - app_id + - kind + - app_display_name + - device_display_name + - lang + - data + examples: + response: + value: { + "pushers": [ + { + "pushkey": "Xp/MzCt8/9DcSNE9cuiaoT5Ac55job3TdLSSmtmYl4A=", + "kind": "http", + "app_id": "face.mcapp.appy.prod", + "app_display_name": "Appy McAppface", + "device_display_name": "Alice's Phone", + "profile_tag": "xyz", + "lang": "en-US", + "data": { + "url": "https://example.com/_matrix/push/v1/notify" + } + } + ] + } tags: - Push notifications - "/pushers/set": + /pushers/set: post: summary: Modify a pusher for this user on the homeserver. description: |- @@ -147,131 +137,156 @@ paths: operationId: postPusher security: - accessToken: [] - parameters: - - in: body - name: pusher - description: The pusher information. - required: true - schema: - type: object - example: { - "lang": "en", - "kind": "http", - "app_display_name": "Mat Rix", - "device_display_name": "iPhone 9", - "profile_tag": "xxyyzz", - "app_id": "com.example.app.ios", - "pushkey": "APA91bHPRgkF3JUikC4ENAHEeMrd41Zxv3hVZjC9KtT8OvPVGJ-hQMRKRrZuJAEcl7B338qju59zJMjw2DELjzEvxwYv7hH5Ynpc1ODQ0aT4U4OFEeco8ohsN5PjL1iC2dNtk2BAokeMCg2ZXKqpc8FXKmhX94kIxQ", - "data": { - "url": "https://push-gateway.location.here/_matrix/push/v1/notify", - "format": "event_id_only" - }, - "append": false - } - properties: - pushkey: - type: string - description: |- - This is a unique identifier for this pusher. The value you - should use for this is the routing or destination address - information for the notification, for example, the APNS token - for APNS or the Registration ID for GCM. If your notification - client has no such concept, use any unique identifier. - Max length, 512 bytes. + requestBody: + content: + application/json: + schema: + type: object + example: { + "lang": "en", + "kind": "http", + "app_display_name": "Mat Rix", + "device_display_name": "iPhone 9", + "profile_tag": "xxyyzz", + "app_id": "com.example.app.ios", + "pushkey": "APA91bHPRgkF3JUikC4ENAHEeMrd41Zxv3hVZjC9KtT8OvPVGJ-hQMRKRrZuJAEcl7B338qju59zJMjw2DELjzEvxwYv7hH5Ynpc1ODQ0aT4U4OFEeco8ohsN5PjL1iC2dNtk2BAokeMCg2ZXKqpc8FXKmhX94kIxQ", + "data": { + "url": "https://push-gateway.location.here/_matrix/push/v1/notify", + "format": "event_id_only" + }, + "append": false + } + properties: + pushkey: + type: string + description: |- + This is a unique identifier for this pusher. The value you + should use for this is the routing or destination address + information for the notification, for example, the APNS token + for APNS or the Registration ID for GCM. If your notification + client has no such concept, use any unique identifier. + Max length, 512 bytes. - If the `kind` is `"email"`, this is the email address to - send notifications to. - kind: - type: - - "string" - - "null" - description: |- - The kind of pusher to configure. `"http"` makes a pusher that - sends HTTP pokes. `"email"` makes a pusher that emails the - user with unread notifications. `null` deletes the pusher. - app_id: - type: string - description: |- - This is a reverse-DNS style identifier for the application. - It is recommended that this end with the platform, such that - different platform versions get different app identifiers. - Max length, 64 chars. + If the `kind` is `"email"`, this is the email address to + send notifications to. + kind: + description: |- + The kind of pusher to configure. `"http"` makes a pusher that + sends HTTP pokes. `"email"` makes a pusher that emails the + user with unread notifications. `null` deletes the pusher. + nullable: true + type: string + app_id: + type: string + description: |- + This is a reverse-DNS style identifier for the application. + It is recommended that this end with the platform, such that + different platform versions get different app identifiers. + Max length, 64 chars. - If the `kind` is `"email"`, this is `"m.email"`. - app_display_name: - type: string - description: |- - Required if `kind` is not `null`. A string that will allow the - user to identify what application owns this pusher. - device_display_name: - type: string - description: |- - Required if `kind` is not `null`. A string that will allow the - user to identify what device owns this pusher. - profile_tag: - type: string - description: |- - This string determines which set of device specific rules this - pusher executes. - lang: - type: string - description: |- - Required if `kind` is not `null`. The preferred language for - receiving notifications (e.g. 'en' or 'en-US'). - data: - type: object - description: |- - Required if `kind` is not `null`. A dictionary of information - for the pusher implementation itself. If `kind` is `http`, - this should contain `url` which is the URL to use to send - notifications to. - title: PusherData - properties: - url: - type: string - format: uri - description: |- - Required if `kind` is `http`. The URL to use to send - notifications to. MUST be an HTTPS URL with a path of - `/_matrix/push/v1/notify`. - example: "https://push-gateway.location.here/_matrix/push/v1/notify" - format: - type: string - description: |- - The format to send notifications in to Push Gateways if the - `kind` is `http`. The details about what fields the - homeserver should send to the push gateway are defined in the - [Push Gateway Specification](/push-gateway-api/). Currently the only format - available is 'event_id_only'. - append: - type: boolean - description: |- - If true, the homeserver should add another pusher with the - given pushkey and App ID in addition to any others with - different user IDs. Otherwise, the homeserver must remove any - other pushers with the same App ID and pushkey for different - users. The default is `false`. - required: ['kind', 'app_id', 'pushkey'] + If the `kind` is `"email"`, this is `"m.email"`. + app_display_name: + type: string + description: |- + Required if `kind` is not `null`. A string that will allow the + user to identify what application owns this pusher. + device_display_name: + type: string + description: |- + Required if `kind` is not `null`. A string that will allow the + user to identify what device owns this pusher. + profile_tag: + type: string + description: |- + This string determines which set of device specific rules this + pusher executes. + lang: + type: string + description: |- + Required if `kind` is not `null`. The preferred language for + receiving notifications (e.g. 'en' or 'en-US'). + data: + type: object + description: |- + Required if `kind` is not `null`. A dictionary of information + for the pusher implementation itself. If `kind` is `http`, + this should contain `url` which is the URL to use to send + notifications to. + title: PusherData + properties: + url: + type: string + format: uri + description: |- + Required if `kind` is `http`. The URL to use to send + notifications to. MUST be an HTTPS URL with a path of + `/_matrix/push/v1/notify`. + example: https://push-gateway.location.here/_matrix/push/v1/notify + format: + type: string + description: |- + The format to send notifications in to Push Gateways if the + `kind` is `http`. The details about what fields the + homeserver should send to the push gateway are defined in the + [Push Gateway Specification](/push-gateway-api/). Currently the only format + available is 'event_id_only'. + append: + type: boolean + description: |- + If true, the homeserver should add another pusher with the + given pushkey and App ID in addition to any others with + different user IDs. Otherwise, the homeserver must remove any + other pushers with the same App ID and pushkey for different + users. The default is `false`. + required: + - kind + - app_id + - pushkey + description: The pusher information. + required: true responses: - 200: + "200": description: The pusher was set. - examples: - application/json: {} - schema: - type: object - description: An empty object. - 400: + content: + application/json: + schema: + type: object + description: An empty object. + examples: + response: + value: {} + "400": description: One or more of the pusher values were invalid. - examples: - application/json: { - "error": "Missing parameters: lang, data", - "errcode": "M_MISSING_PARAM" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "error": "Missing parameters: lang, data", + "errcode": "M_MISSING_PARAM" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Push notifications +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 diff --git a/data/api/client-server/pushrules.yaml b/data/api/client-server/pushrules.yaml index 817138d16..32812a2a1 100644 --- a/data/api/client-server/pushrules.yaml +++ b/data/api/client-server/pushrules.yaml @@ -11,23 +11,12 @@ # 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 Push Rules 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 Push Rules API + version: 1.0.0 paths: - "/pushrules/": + /pushrules/: get: summary: Retrieve all push rulesets. description: |- @@ -39,321 +28,344 @@ paths: security: - accessToken: [] responses: - 200: + "200": description: All the push rulesets for this user. - schema: - type: object - required: ["global"] - properties: - global: + content: + application/json: + schema: type: object - description: The global ruleset. - title: Ruleset - allOf: [ - "$ref": "definitions/push_ruleset.yaml" - ] - examples: - application/json: { - "global": { - "content": [ + required: + - global + properties: + global: + type: object + description: The global ruleset. + title: Ruleset + allOf: + - $ref: definitions/push_ruleset.yaml + examples: + response: + value: { + "global": { + "content": [ { - "actions": [ - "notify", - { - "set_tweak": "sound", - "value": "default" - }, - { - "set_tweak": "highlight" - } - ], - "default": true, - "enabled": true, - "pattern": "alice", - "rule_id": ".m.rule.contains_user_name" + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "default" + }, + { + "set_tweak": "highlight" + } + ], + "default": true, + "enabled": true, + "pattern": "alice", + "rule_id": ".m.rule.contains_user_name" } - ], - "override": [ + ], + "override": [ { - "actions": [], - "conditions": [], - "default": true, - "enabled": false, - "rule_id": ".m.rule.master" + "actions": [], + "conditions": [], + "default": true, + "enabled": false, + "rule_id": ".m.rule.master" }, { - "actions": [], - "conditions": [ - { - "key": "content.msgtype", - "kind": "event_match", - "pattern": "m.notice" - } - ], - "default": true, - "enabled": true, - "rule_id": ".m.rule.suppress_notices" + "actions": [], + "conditions": [ + { + "key": "content.msgtype", + "kind": "event_match", + "pattern": "m.notice" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.suppress_notices" } - ], - "room": [], - "sender": [], - "underride": [ + ], + "room": [], + "sender": [], + "underride": [ { - "actions": [ - "notify", - { - "set_tweak": "sound", - "value": "ring" - }, - { - "set_tweak": "highlight", - "value": false - } - ], - "conditions": [ - { - "key": "type", - "kind": "event_match", - "pattern": "m.call.invite" - } - ], - "default": true, - "enabled": true, - "rule_id": ".m.rule.call" + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "ring" + }, + { + "set_tweak": "highlight", + "value": false + } + ], + "conditions": [ + { + "key": "type", + "kind": "event_match", + "pattern": "m.call.invite" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.call" }, { - "actions": [ - "notify", - { - "set_tweak": "sound", - "value": "default" - }, - { - "set_tweak": "highlight" - } - ], - "conditions": [ - { - "kind": "contains_display_name" - } - ], - "default": true, - "enabled": true, - "rule_id": ".m.rule.contains_display_name" + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "default" + }, + { + "set_tweak": "highlight" + } + ], + "conditions": [ + { + "kind": "contains_display_name" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.contains_display_name" }, { - "actions": [ - "notify", - { - "set_tweak": "sound", - "value": "default" - }, - { - "set_tweak": "highlight", - "value": false - } - ], - "conditions": [ - { - "kind": "room_member_count", - "is": "2" - }, - { - "kind": "event_match", - "key": "type", - "pattern": "m.room.message" - } - ], - "default": true, - "enabled": true, - "rule_id": ".m.rule.room_one_to_one" + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "default" + }, + { + "set_tweak": "highlight", + "value": false + } + ], + "conditions": [ + { + "kind": "room_member_count", + "is": "2" + }, + { + "kind": "event_match", + "key": "type", + "pattern": "m.room.message" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.room_one_to_one" }, { - "actions": [ - "notify", - { - "set_tweak": "sound", - "value": "default" - }, - { - "set_tweak": "highlight", - "value": false - } - ], - "conditions": [ - { - "key": "type", - "kind": "event_match", - "pattern": "m.room.member" - }, - { - "key": "content.membership", - "kind": "event_match", - "pattern": "invite" - }, - { - "key": "state_key", - "kind": "event_match", - "pattern": "@alice:example.com" - } - ], - "default": true, - "enabled": true, - "rule_id": ".m.rule.invite_for_me" + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "default" + }, + { + "set_tweak": "highlight", + "value": false + } + ], + "conditions": [ + { + "key": "type", + "kind": "event_match", + "pattern": "m.room.member" + }, + { + "key": "content.membership", + "kind": "event_match", + "pattern": "invite" + }, + { + "key": "state_key", + "kind": "event_match", + "pattern": "@alice:example.com" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.invite_for_me" }, { - "actions": [ - "notify", - { - "set_tweak": "highlight", - "value": false - } - ], - "conditions": [ - { - "key": "type", - "kind": "event_match", - "pattern": "m.room.member" - } - ], - "default": true, - "enabled": true, - "rule_id": ".m.rule.member_event" + "actions": [ + "notify", + { + "set_tweak": "highlight", + "value": false + } + ], + "conditions": [ + { + "key": "type", + "kind": "event_match", + "pattern": "m.room.member" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.member_event" }, { - "actions": [ - "notify", - { - "set_tweak": "highlight", - "value": false - } - ], - "conditions": [ - { - "key": "type", - "kind": "event_match", - "pattern": "m.room.message" - } - ], - "default": true, - "enabled": true, - "rule_id": ".m.rule.message" + "actions": [ + "notify", + { + "set_tweak": "highlight", + "value": false + } + ], + "conditions": [ + { + "key": "type", + "kind": "event_match", + "pattern": "m.room.message" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.message" } - ] - } - } + ] + } + } tags: - Push notifications "/pushrules/{scope}/{kind}/{ruleId}": get: summary: Retrieve a push rule. - description: |- - Retrieve a single specified push rule. + description: Retrieve a single specified push rule. operationId: getPushRule security: - accessToken: [] parameters: - in: path - type: string name: scope required: true - x-example: "global" - description: |- - `global` to specify global rules. + description: "`global` to specify global rules." + example: global + schema: + type: string - in: path - type: string name: kind required: true - x-example: content - enum: ["override", "underride", "sender", "room", "content"] description: | The kind of rule + example: content + schema: + type: string + enum: + - override + - underride + - sender + - room + - content - in: path - type: string name: ruleId required: true - x-example: "nocake" description: | The identifier for the rule. + example: nocake + schema: + type: string responses: - 200: + "200": description: |- The specific push rule. This will also include keys specific to the rule itself such as the rule's `actions` and `conditions` if set. - examples: - application/json: { - "actions": [], - "pattern": "cake*lie", - "rule_id": "nocake", - "enabled": true, - "default": false - } - schema: - type: object - description: The push rule. - allOf: [ - "$ref": "definitions/push_rule.yaml" - ] - 404: - description: |- - The push rule does not exist. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "The push rule was not found." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + type: object + description: The push rule. + allOf: + - $ref: definitions/push_rule.yaml + examples: + response: + value: { + "actions": [], + "pattern": "cake*lie", + "rule_id": "nocake", + "enabled": true, + "default": false + } + "404": + description: The push rule does not exist. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "The push rule was not found." + } tags: - Push notifications delete: summary: Delete a push rule. - description: |- - This endpoint removes the push rule defined in the path. + description: This endpoint removes the push rule defined in the path. operationId: deletePushRule security: - accessToken: [] parameters: - in: path - type: string name: scope required: true - x-example: "global" - description: |- - `global` to specify global rules. + description: "`global` to specify global rules." + example: global + schema: + type: string - in: path - type: string name: kind required: true - x-example: content - enum: ["override", "underride", "sender", "room", "content"] description: | The kind of rule + example: content + schema: + type: string + enum: + - override + - underride + - sender + - room + - content - in: path - type: string name: ruleId required: true - x-example: "nocake" description: | The identifier for the rule. + example: nocake + schema: + type: string responses: - 200: + "200": description: The push rule was deleted. - examples: - application/json: { - } - schema: - type: object # empty json object - 404: - description: |- - The push rule does not exist. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "The push rule was not found." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "404": + description: The push rule does not exist. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "The push rule was not found." + } tags: - Push notifications put: @@ -380,305 +392,369 @@ paths: - accessToken: [] parameters: - in: path - type: string name: scope required: true - x-example: "global" - description: |- - `global` to specify global rules. + description: "`global` to specify global rules." + example: global + schema: + type: string - in: path - type: string name: kind required: true - x-example: content - enum: ["override", "underride", "sender", "room", "content"] description: | The kind of rule + example: content + schema: + type: string + enum: + - override + - underride + - sender + - room + - content - in: path - type: string name: ruleId required: true - x-example: "nocake" description: | The identifier for the rule. If the string starts with a dot ("."), the request MUST be rejected as this is reserved for server-default rules. Slashes ("/") and backslashes ("\\") are also not allowed. + example: nocake + schema: + type: string - in: query - type: string name: before required: false - x-example: someRuleId description: |- Use 'before' with a `rule_id` as its value to make the new rule the next-most important rule with respect to the given user defined rule. It is not possible to add a rule relative to a predefined server rule. + example: someRuleId + schema: + type: string - in: query - type: string name: after required: false - x-example: anotherRuleId description: |- This makes the new rule the next-less important rule relative to the given user defined rule. It is not possible to add a rule relative to a predefined server rule. - - in: body - name: pushrule - description: |- - The push rule data. Additional top-level keys may be present depending - on the parameters for the rule `kind`. - required: true + example: anotherRuleId schema: - type: object - example: { + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { "pattern": "cake*lie", - "actions": ["notify"] + "actions": [ + "notify" + ] } - properties: - actions: - type: array - description: |- - The action(s) to perform when the conditions for this rule are met. - items: - type: - - string - - object - conditions: - type: array - description: |- - The conditions that must hold true for an event in order for a - rule to be applied to an event. A rule with no conditions - always matches. Only applicable to `underride` and `override` rules. - items: - type: object - allOf: [ "$ref": "definitions/push_condition.yaml" ] - pattern: - type: string - description: |- - Only applicable to `content` rules. The glob-style pattern to match against. - required: ["actions"] + properties: + actions: + type: array + description: The action(s) to perform when the conditions for this rule are met. + items: + oneOf: + - type: string + - type: object + conditions: + type: array + description: |- + The conditions that must hold true for an event in order for a + rule to be applied to an event. A rule with no conditions + always matches. Only applicable to `underride` and `override` rules. + items: + type: object + allOf: + - $ref: definitions/push_condition.yaml + pattern: + type: string + description: Only applicable to `content` rules. The glob-style pattern to match + against. + required: + - actions + description: |- + The push rule data. Additional top-level keys may be present depending + on the parameters for the rule `kind`. + required: true responses: - 200: + "200": description: The push rule was created/updated. - examples: - application/json: { - } - schema: - type: object # empty json object - 400: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "400": description: There was a problem configuring this push rule. - examples: - application/json: { - "error": "before/after rule not found: someRuleId", - "errcode": "M_UNKNOWN" - } - schema: - "$ref": "definitions/errors/error.yaml" - 404: - description: |- - The push rule does not exist (when updating a push rule). - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "The push rule was not found." - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "error": "before/after rule not found: someRuleId", + "errcode": "M_UNKNOWN" + } + "404": + description: The push rule does not exist (when updating a push rule). + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "The push rule was not found." + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Push notifications "/pushrules/{scope}/{kind}/{ruleId}/enabled": get: - summary: "Get whether a push rule is enabled" - description: - This endpoint gets whether the specified push rule is enabled. + summary: Get whether a push rule is enabled + description: This endpoint gets whether the specified push rule is enabled. operationId: isPushRuleEnabled security: - accessToken: [] parameters: - in: path - type: string name: scope required: true - x-example: "global" description: |- Either `global` or `device/` to specify global rules or device rules for the given `profile_tag`. + example: global + schema: + type: string - in: path - type: string name: kind required: true - x-example: cake - enum: ["override", "underride", "sender", "room", "content"] description: | The kind of rule + example: cake + schema: + type: string + enum: + - override + - underride + - sender + - room + - content - in: path - type: string name: ruleId required: true - x-example: nocake description: | The identifier for the rule. + example: nocake + schema: + type: string responses: - 200: + "200": description: Whether the push rule is enabled. - examples: - application/json: { - "enabled": true - } - schema: - type: object - properties: - enabled: - type: boolean - description: Whether the push rule is enabled or not. - required: ["enabled"] - 404: - description: |- - The push rule does not exist. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "The push rule was not found." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + type: object + properties: + enabled: + type: boolean + description: Whether the push rule is enabled or not. + required: + - enabled + examples: + response: + value: { + "enabled": true + } + "404": + description: The push rule does not exist. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "The push rule was not found." + } tags: - Push notifications put: - summary: "Enable or disable a push rule." - description: |- - This endpoint allows clients to enable or disable the specified push rule. + summary: Enable or disable a push rule. + description: This endpoint allows clients to enable or disable the specified + push rule. operationId: setPushRuleEnabled security: - accessToken: [] parameters: - in: path - type: string name: scope required: true - x-example: "global" - description: |- - `global` to specify global rules. + description: "`global` to specify global rules." + example: global + schema: + type: string - in: path - type: string name: kind required: true - x-example: content - enum: ["override", "underride", "sender", "room", "content"] description: | The kind of rule + example: content + schema: + type: string + enum: + - override + - underride + - sender + - room + - content - in: path - type: string name: ruleId required: true - x-example: "nocake" description: | The identifier for the rule. - - in: body - name: body - description: | - Whether the push rule is enabled or not. - required: true + example: nocake schema: - type: object - properties: - enabled: - type: boolean - description: Whether the push rule is enabled or not. - required: ["enabled"] - example: { + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + enabled: + type: boolean + description: Whether the push rule is enabled or not. + required: + - enabled + example: { "enabled": true } + description: | + Whether the push rule is enabled or not. + required: true responses: - 200: + "200": description: The push rule was enabled or disabled. - examples: - application/json: { - } - schema: - type: object - 404: - description: |- - The push rule does not exist. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "The push rule was not found." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "404": + description: The push rule does not exist. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "The push rule was not found." + } tags: - Push notifications "/pushrules/{scope}/{kind}/{ruleId}/actions": get: - summary: "The actions for a push rule" - description: - This endpoint get the actions for the specified push rule. + summary: The actions for a push rule + description: This endpoint get the actions for the specified push rule. operationId: getPushRuleActions security: - accessToken: [] parameters: - in: path - type: string name: scope required: true - x-example: "global" description: |- Either `global` or `device/` to specify global rules or device rules for the given `profile_tag`. + example: global + schema: + type: string - in: path - type: string name: kind required: true - x-example: content - enum: ["override", "underride", "sender", "room", "content"] description: | The kind of rule + example: content + schema: + type: string + enum: + - override + - underride + - sender + - room + - content - in: path - type: string name: ruleId required: true - x-example: nocake description: | The identifier for the rule. + example: nocake + schema: + type: string responses: - 200: + "200": description: The actions for this push rule. - examples: - application/json: { - "actions": [ - "notify", - {"set_tweak": "sound", "value": "bing"} - ] - } - schema: - type: object - properties: - actions: - type: array - description: The action(s) to perform for this rule. - items: - type: - - string - - object - required: ["actions"] - 404: - description: |- - The push rule does not exist. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "The push rule was not found." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + type: object + properties: + actions: + type: array + description: The action(s) to perform for this rule. + items: + oneOf: + - type: string + - type: object + required: + - actions + examples: + response: + value: { + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "bing" + } + ] + } + "404": + description: The push rule does not exist. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "The push rule was not found." + } tags: - Push notifications put: - summary: "Set the actions for a push rule." + summary: Set the actions for a push rule. description: |- This endpoint allows clients to change the actions of a push rule. This can be used to change the actions of builtin rules. @@ -687,66 +763,96 @@ paths: - accessToken: [] parameters: - in: path - type: string name: scope required: true - x-example: "global" - description: |- - `global` to specify global rules. + description: "`global` to specify global rules." + example: global + schema: + type: string - in: path - type: string name: kind required: true - x-example: room - enum: ["override", "underride", "sender", "room", "content"] description: | The kind of rule + example: room + schema: + type: string + enum: + - override + - underride + - sender + - room + - content - in: path - type: string name: ruleId required: true - x-example: "#spam:example.com" description: | The identifier for the rule. - - in: body - name: body - description: | - The action(s) to perform when the conditions for this rule are met. - required: true + example: "#spam:example.com" schema: - type: object - properties: - actions: - type: array - description: The action(s) to perform for this rule. - items: - type: - - string - - object - required: ["actions"] - example: { + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + actions: + type: array + description: The action(s) to perform for this rule. + items: + oneOf: + - type: string + - type: object + required: + - actions + example: { "actions": [ "notify", - {"set_tweak": "highlight"} + { + "set_tweak": "highlight" + } ] } + description: | + The action(s) to perform when the conditions for this rule are met. + required: true responses: - 200: + "200": description: The actions for the push rule were set. - examples: - application/json: { - } - schema: - type: object - 404: - description: |- - The push rule does not exist. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "The push rule was not found." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "404": + description: The push rule does not exist. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "The push rule was not found." + } tags: - Push notifications +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 diff --git a/data/api/client-server/read_markers.yaml b/data/api/client-server/read_markers.yaml index d5993f67b..5372df343 100644 --- a/data/api/client-server/read_markers.yaml +++ b/data/api/client-server/read_markers.yaml @@ -12,21 +12,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 Read Marker 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 Read Marker API + version: 1.0.0 paths: "/rooms/{roomId}/read_markers": post: @@ -39,52 +28,72 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room ID to set the read marker in for the user. required: true - x-example: "!somewhere:example.org" - - in: body - name: body - description: The read marker and optional read receipt locations. - required: true + example: "!somewhere:example.org" schema: - type: object - properties: - "m.fully_read": - type: string - description: |- - The event ID the read marker should be located at. The - event MUST belong to the room. - example: "$somewhere:example.org" - x-changedInMatrixVersion: - 1.4: | - This property is no longer required. - "m.read": - type: string - description: |- - The event ID to set the read receipt location at. This is - equivalent to calling `/receipt/m.read/$elsewhere:example.org` - and is provided here to save that extra call. - example: "$elsewhere:example.org" - "m.read.private": - x-addedInMatrixVersion: "1.4" - type: string - description: |- - The event ID to set the *private* read receipt location at. This - equivalent to calling `/receipt/m.read.private/$elsewhere:example.org` - and is provided here to save that extra call. - example: "$elsewhere:example.org" + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + m.fully_read: + type: string + description: |- + The event ID the read marker should be located at. The + event MUST belong to the room. + example: $somewhere:example.org + x-changedInMatrixVersion: + "1.4": | + This property is no longer required. + m.read: + type: string + description: |- + The event ID to set the read receipt location at. This is + equivalent to calling `/receipt/m.read/$elsewhere:example.org` + and is provided here to save that extra call. + example: $elsewhere:example.org + m.read.private: + x-addedInMatrixVersion: "1.4" + type: string + description: |- + The event ID to set the *private* read receipt location at. This + equivalent to calling `/receipt/m.read.private/$elsewhere:example.org` + and is provided here to save that extra call. + example: $elsewhere:example.org + description: The read marker and optional read receipt locations. + required: true responses: - 200: - description: |- - The read marker, and read receipt(s) if provided, have been updated. - schema: - type: object - properties: {} - 429: + "200": + description: The read marker, and read receipt(s) if provided, have been updated. + content: + application/json: + schema: + type: object + properties: {} + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Read Markers +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 diff --git a/data/api/client-server/receipts.yaml b/data/api/client-server/receipts.yaml index 0b8d45937..279cdda1a 100644 --- a/data/api/client-server/receipts.yaml +++ b/data/api/client-server/receipts.yaml @@ -12,21 +12,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 Receipts 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 Receipts API + version: 1.0.0 paths: "/rooms/{roomId}/receipt/{receiptType}/{eventId}": post: @@ -39,13 +28,13 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room in which to send the event. required: true - x-example: "!wefuh21ffskfuh345:example.com" + example: "!wefuh21ffskfuh345:example.com" + schema: + type: string - in: path - type: string name: receiptType description: |- The type of receipt to send. This can also be `m.fully_read` as an @@ -55,63 +44,92 @@ paths: effectively calls `/read_markers` internally when presented with a receipt type of `m.fully_read`. required: true - x-example: "m.read" x-changedInMatrixVersion: - 1.4: | + "1.4": | Allow `m.read.private` receipts and `m.fully_read` markers to be set. - enum: ["m.read", "m.read.private", "m.fully_read"] + example: m.read + schema: + type: string + enum: + - m.read + - m.read.private + - m.fully_read - in: path - type: string name: eventId description: The event ID to acknowledge up to. required: true - x-example: "$1924376522eioj:example.com" - - in: body - name: receipt - description: |- - Extra receipt information to attach to `content` if any. The - server will automatically set the `ts` field. - required: true + example: $1924376522eioj:example.com schema: - type: object - properties: - thread_id: - type: string - x-addedInMatrixVersion: "1.4" - description: |- + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + thread_id: + type: string + x-addedInMatrixVersion: "1.4" + description: |- The root thread event's ID (or `main`) for which thread this receipt is intended to be under. If not specified, the read receipt is *unthreaded* (default). - example: { - "thread_id": "main" - } + example: { + "thread_id": "main" + } + description: |- + Extra receipt information to attach to `content` if any. The + server will automatically set the `ts` field. + required: true responses: - 200: + "200": description: The receipt was sent. - examples: - application/json: { - } - schema: - type: object - maxProperties: 0 # empty json object - 429: - description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" - 400: + content: + application/json: + schema: + type: object + maxProperties: 0 + examples: + response: + value: {} + "400": description: |- The `thread_id` is invalid in some way. For example: * It is not a string. * It is empty. * It is provided for an incompatible receipt type. * The `event_id` is not related to the `thread_id`. - schema: - $ref: "definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_INVALID_PARAM", - "error": "thread_id field must be a non-empty string" - } + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_INVALID_PARAM", + "error": "thread_id field must be a non-empty string" + } + "429": + description: This request was rate-limited. + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml 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 diff --git a/data/api/client-server/redaction.yaml b/data/api/client-server/redaction.yaml index 8fa9cbef5..aca69fa63 100644 --- a/data/api/client-server/redaction.yaml +++ b/data/api/client-server/redaction.yaml @@ -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 message redaction 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 message redaction API + version: 1.0.0 paths: "/rooms/{roomId}/redact/{eventId}/{txnId}": put: @@ -47,50 +36,71 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room from which to redact the event. required: true - x-example: "!637q39766251:example.com" + example: "!637q39766251:example.com" + schema: + type: string - in: path - type: string name: eventId description: The ID of the event to redact required: true - x-example: "bai2b1i9:matrix.org" + example: bai2b1i9:matrix.org + schema: + type: string - in: path name: txnId - type: string description: |- The [transaction ID](/client-server-api/#transaction-identifiers) for this event. Clients should generate a unique ID; it will be used by the server to ensure idempotency of requests. required: true - x-example: "37" - - in: body - name: body - required: true + example: "37" schema: - type: object - example: { + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { "reason": "Indecent material" } - properties: - reason: - type: string - description: The reason for the event being redacted. + properties: + reason: + type: string + description: The reason for the event being redacted. + required: true responses: - 200: - description: "An ID for the redaction event." - examples: - application/json: { - "event_id": "$YUwQidLecu:example.com" - } - schema: - type: object - properties: - event_id: - type: string - description: |- - A unique identifier for the event. + "200": + description: An ID for the redaction event. + content: + application/json: + schema: + type: object + properties: + event_id: + type: string + description: A unique identifier for the event. + examples: + response: + value: { + "event_id": "$YUwQidLecu:example.com" + } 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 diff --git a/data/api/client-server/refresh.yaml b/data/api/client-server/refresh.yaml index 5923d3b72..f40bd5163 100644 --- a/data/api/client-server/refresh.yaml +++ b/data/api/client-server/refresh.yaml @@ -11,21 +11,12 @@ # 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 Registration and Login API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json + title: Matrix Client-Server Registration and Login API + version: 1.0.0 paths: - "/refresh": + /refresh: post: x-addedInMatrixVersion: "1.3" summary: Refresh an access token @@ -48,63 +39,81 @@ paths: Application Service identity assertion is disabled for this endpoint. operationId: refresh - parameters: - - in: body - name: body - required: true - schema: - type: object - example: { + requestBody: + content: + application/json: + schema: + type: object + example: { "refresh_token": "some_token" } - properties: - refresh_token: - type: string - description: The refresh token - required: - - refresh_token + properties: + refresh_token: + type: string + description: The refresh token + required: + - refresh_token + required: true responses: - 200: + "200": description: A new access token and refresh token were generated. - examples: - application/json: { - "access_token": "a_new_token", - "expires_in_ms": 60000, - "refresh_token": "another_new_token" - } - schema: - type: object - properties: - access_token: - type: string - description: |- - The new access token to use. - refresh_token: - type: string - description: |- - The new refresh token to use when the access token needs to - be refreshed again. If not given, the old refresh token can - be re-used. - expires_in_ms: - type: integer - description: |- - The lifetime of the access token, in milliseconds. If not - given, the client can assume that the access token will not - expire. - required: - - access_token - 401: - description: |- - The provided token was unknown, or has already been used. - examples: - application/json: { - "errcode": "M_UNKNOWN_TOKEN", - "error": "Soft logged out", - "soft_logout": true - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + type: object + properties: + access_token: + type: string + description: The new access token to use. + refresh_token: + type: string + description: |- + The new refresh token to use when the access token needs to + be refreshed again. If not given, the old refresh token can + be re-used. + expires_in_ms: + type: integer + description: |- + The lifetime of the access token, in milliseconds. If not + given, the client can assume that the access token will not + expire. + required: + - access_token + examples: + response: + value: { + "access_token": "a_new_token", + "expires_in_ms": 60000, + "refresh_token": "another_new_token" + } + "401": + description: The provided token was unknown, or has already been used. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_UNKNOWN_TOKEN", + "error": "Soft logged out", + "soft_logout": true + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 diff --git a/data/api/client-server/registration.yaml b/data/api/client-server/registration.yaml index 29bd41961..d961ac177 100644 --- a/data/api/client-server/registration.yaml +++ b/data/api/client-server/registration.yaml @@ -12,21 +12,12 @@ # 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 Registration API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json + title: Matrix Client-Server Registration API + version: 1.0.0 paths: - "/register": + /register: post: summary: Register for an account on this homeserver. description: |- @@ -73,129 +64,132 @@ paths: parameters: - in: query name: kind - type: string - # swagger-UI overrides the default with the example, so better make the - # example the default. - x-example: user required: false - default: user - enum: - - guest - - user description: The kind of account to register. Defaults to `user`. - - in: body - name: body - required: true - schema: - type: object - properties: - auth: - description: |- + example: user + schema: + type: string + enum: + - guest + - user + default: user + requestBody: + content: + application/json: + schema: + type: object + properties: + auth: + description: |- Additional authentication information for the user-interactive authentication API. Note that this information is *not* used to define how the registered user should be authenticated, but is instead used to authenticate the `register` call itself. - allOf: - - "$ref": "definitions/auth_data.yaml" - username: - type: string - description: |- - The basis for the localpart of the desired Matrix ID. If omitted, - the homeserver MUST generate a Matrix ID local part. - example: cheeky_monkey - password: - type: string - description: The desired password for the account. - example: ilovebananas - device_id: - type: string - description: |- - ID of the client device. If this does not correspond to a - known client device, a new device will be created. The server - will auto-generate a device_id if this is not specified. - example: GHTYAJCE - initial_device_display_name: - type: string - description: |- - A display name to assign to the newly-created device. Ignored - if `device_id` corresponds to a known device. - example: Jungle Phone - inhibit_login: - type: boolean - description: |- - If true, an `access_token` and `device_id` should not be - returned from this call, therefore preventing an automatic - login. Defaults to false. - example: false - refresh_token: - type: boolean - description: |- - If true, the client supports refresh tokens. - x-addedInMatrixVersion: "1.3" + allOf: + - $ref: definitions/auth_data.yaml + username: + type: string + description: |- + The basis for the localpart of the desired Matrix ID. If omitted, + the homeserver MUST generate a Matrix ID local part. + example: cheeky_monkey + password: + type: string + description: The desired password for the account. + example: ilovebananas + device_id: + type: string + description: |- + ID of the client device. If this does not correspond to a + known client device, a new device will be created. The server + will auto-generate a device_id if this is not specified. + example: GHTYAJCE + initial_device_display_name: + type: string + description: |- + A display name to assign to the newly-created device. Ignored + if `device_id` corresponds to a known device. + example: Jungle Phone + inhibit_login: + type: boolean + description: |- + If true, an `access_token` and `device_id` should not be + returned from this call, therefore preventing an automatic + login. Defaults to false. + example: false + refresh_token: + type: boolean + description: If true, the client supports refresh tokens. + x-addedInMatrixVersion: "1.3" + required: true responses: - 200: + "200": description: The account has been registered. - examples: - application/json: { - "user_id": "@cheeky_monkey:matrix.org", - "access_token": "abc123", - "device_id": "GHTYAJCE" - } - schema: - type: object - properties: - user_id: - type: string - description: |- - The fully-qualified Matrix user ID (MXID) that has been registered. - - Any user ID returned by this API must conform to the grammar given in the - [Matrix specification](/appendices/#user-identifiers). - access_token: - type: string - description: |- - An access token for the account. - This access token can then be used to authorize other requests. - Required if the `inhibit_login` option is false. - refresh_token: - type: string - description: |- - A refresh token for the account. This token can be used to - obtain a new access token when it expires by calling the - `/refresh` endpoint. - - Omitted if the `inhibit_login` option is true. - x-addedInMatrixVersion: "1.3" - expires_in_ms: - type: integer - description: |- - The lifetime of the access token, in milliseconds. Once - the access token has expired a new access token can be - obtained by using the provided refresh token. If no - refresh token is provided, the client will need to re-log in - to obtain a new access token. If not given, the client can - assume that the access token will not expire. - - Omitted if the `inhibit_login` option is true. - x-addedInMatrixVersion: "1.3" - home_server: - type: string - description: |- - The server_name of the homeserver on which the account has - been registered. - - **Deprecated**. Clients should extract the server_name from - `user_id` (by splitting at the first colon) if they require - it. Note also that `homeserver` is not spelt this way. - device_id: - type: string - description: |- - ID of the registered device. Will be the same as the - corresponding parameter in the request, if one was specified. - Required if the `inhibit_login` option is false. - required: ['user_id'] - 400: + content: + application/json: + schema: + type: object + properties: + user_id: + type: string + description: |- + The fully-qualified Matrix user ID (MXID) that has been registered. + + Any user ID returned by this API must conform to the grammar given in the + [Matrix specification](/appendices/#user-identifiers). + access_token: + type: string + description: |- + An access token for the account. + This access token can then be used to authorize other requests. + Required if the `inhibit_login` option is false. + refresh_token: + type: string + description: |- + A refresh token for the account. This token can be used to + obtain a new access token when it expires by calling the + `/refresh` endpoint. + + Omitted if the `inhibit_login` option is true. + x-addedInMatrixVersion: "1.3" + expires_in_ms: + type: integer + description: |- + The lifetime of the access token, in milliseconds. Once + the access token has expired a new access token can be + obtained by using the provided refresh token. If no + refresh token is provided, the client will need to re-log in + to obtain a new access token. If not given, the client can + assume that the access token will not expire. + + Omitted if the `inhibit_login` option is true. + x-addedInMatrixVersion: "1.3" + home_server: + type: string + description: |- + The server_name of the homeserver on which the account has + been registered. + + **Deprecated**. Clients should extract the server_name from + `user_id` (by splitting at the first colon) if they require + it. Note also that `homeserver` is not spelt this way. + device_id: + type: string + description: |- + ID of the registered device. Will be the same as the + corresponding parameter in the request, if one was specified. + Required if the `inhibit_login` option is false. + required: + - user_id + examples: + response: + value: { + "user_id": "@cheeky_monkey:matrix.org", + "access_token": "abc123", + "device_id": "GHTYAJCE" + } + "400": description: |- Part of the request was invalid. This may include one of the following error codes: @@ -212,69 +206,72 @@ paths: performing User-Interactive Authentication, although they may also return them after authentication is completed if, for example, the requested user ID was registered whilst the client was performing authentication. - examples: - application/json: { - "errcode": "M_USER_IN_USE", - "error": "Desired user ID is already taken." - } - schema: - "$ref": "definitions/errors/error.yaml" - 401: - description: |- - The homeserver requires additional authentication information. - schema: - "$ref": "definitions/auth_response.yaml" - 403: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_USER_IN_USE", + "error": "Desired user ID is already taken." + } + "401": + description: The homeserver requires additional authentication information. + content: + application/json: + schema: + $ref: definitions/auth_response.yaml + "403": description: |- The homeserver does not permit registering the account. This response can be used to identify that a particular `kind` of account is not allowed, or that registration is generally not supported by the homeserver. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "Registration is disabled" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "Registration is disabled" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Account management - "/register/email/requestToken": + /register/email/requestToken: post: - summary: Begins the validation process for an email to be used during registration. + summary: Begins the validation process for an email to be used during + registration. description: |- The homeserver must check that the given email address is **not** already associated with an account on this homeserver. The homeserver should validate the email itself, either by sending a validation email itself or by using a service it has control over. operationId: requestTokenToRegisterEmail - parameters: - - in: body - name: body - required: true - schema: - $ref: "definitions/request_email_validation.yaml" + requestBody: + content: + application/json: + schema: + $ref: definitions/request_email_validation.yaml + required: true responses: - 200: + "200": description: |- An email has been sent to the specified address. Note that this may be an email containing the validation token or it may be informing the user of an error. - schema: - $ref: "definitions/request_token_response.yaml" - 403: - description: The homeserver does not permit the address to be bound. - schema: - $ref: "definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_THREEPID_DENIED", - "error": "Third-party identifier is not allowed" - } - 400: + content: + application/json: + schema: + $ref: definitions/request_token_response.yaml + "400": description: |- Part of the request was invalid. This may include one of the following error codes: @@ -285,48 +282,57 @@ paths: has an account on the homeserver in question. * `M_SERVER_NOT_TRUSTED` : The `id_server` parameter refers to an identity server that is not trusted by this homeserver. - examples: - application/json: { - "errcode": "M_THREEPID_IN_USE", - "error": "The specified address is already in use" - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_IN_USE", + "error": "The specified address is already in use" + } + "403": + description: The homeserver does not permit the address to be bound. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_DENIED", + "error": "Third-party identifier is not allowed" + } tags: - Account management - "/register/msisdn/requestToken": + /register/msisdn/requestToken: post: - summary: Requests a validation token be sent to the given phone number for the purpose of registering an account + summary: Requests a validation token be sent to the given phone number for the + purpose of registering an account description: |- The homeserver must check that the given phone number is **not** already associated with an account on this homeserver. The homeserver should validate the phone number itself, either by sending a validation message itself or by using a service it has control over. operationId: requestTokenToRegisterMSISDN - parameters: - - in: body - name: body - required: true - schema: - $ref: "definitions/request_msisdn_validation.yaml" + requestBody: + content: + application/json: + schema: + $ref: definitions/request_msisdn_validation.yaml + required: true responses: - 200: + "200": description: |- An SMS message has been sent to the specified phone number. Note that this may be an SMS message containing the validation token or it may be informing the user of an error. - schema: - $ref: "definitions/request_token_response.yaml" - 403: - description: The homeserver does not permit the address to be bound. - schema: - $ref: "definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_THREEPID_DENIED", - "error": "Third-party identifier is not allowed" - } - 400: + content: + application/json: + schema: + $ref: definitions/request_token_response.yaml + "400": description: |- Part of the request was invalid. This may include one of the following error codes: @@ -337,18 +343,33 @@ paths: has an account on the homeserver in question. * `M_SERVER_NOT_TRUSTED` : The `id_server` parameter refers to an identity server that is not trusted by this homeserver. - examples: - application/json: { - "errcode": "M_THREEPID_IN_USE", - "error": "The specified address is already in use" - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_IN_USE", + "error": "The specified address is already in use" + } + "403": + description: The homeserver does not permit the address to be bound. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_DENIED", + "error": "Third-party identifier is not allowed" + } tags: - Account management - "/account/password": + /account/password: post: - summary: "Changes a user's password." + summary: Changes a user's password. description: |- Changes the password for an account on this homeserver. @@ -366,53 +387,61 @@ paths: security: - accessToken: [] operationId: changePassword - parameters: - - in: body - name: body - required: true - schema: - type: object - properties: - new_password: - type: string - description: The new password for the account. - example: "ihatebananas" - logout_devices: - type: boolean - description: |- - Whether the user's other access tokens, and their associated devices, should be - revoked if the request succeeds. Defaults to true. - - When `false`, the server can still take advantage of the [soft logout method](/client-server-api/#soft-logout) - for the user's remaining devices. - example: true - auth: - description: |- - Additional authentication information for the user-interactive authentication API. - allOf: - - "$ref": "definitions/auth_data.yaml" - required: ["new_password"] + requestBody: + content: + application/json: + schema: + type: object + properties: + new_password: + type: string + description: The new password for the account. + example: ihatebananas + logout_devices: + type: boolean + description: |- + Whether the user's other access tokens, and their associated devices, should be + revoked if the request succeeds. Defaults to true. + + When `false`, the server can still take advantage of the [soft logout method](/client-server-api/#soft-logout) + for the user's remaining devices. + example: true + auth: + description: Additional authentication information for the user-interactive + authentication API. + allOf: + - $ref: definitions/auth_data.yaml + required: + - new_password + required: true responses: - 200: + "200": description: The password has been changed. - examples: - application/json: {} - schema: - type: object - 401: - description: |- - The homeserver requires additional authentication information. - schema: - "$ref": "definitions/auth_response.yaml" - 429: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "401": + description: The homeserver requires additional authentication information. + content: + application/json: + schema: + $ref: definitions/auth_response.yaml + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Account management - "/account/password/email/requestToken": + /account/password/email/requestToken: post: - summary: Requests a validation token be sent to the given email address for the purpose of resetting a user's password + summary: Requests a validation token be sent to the given email address for the + purpose of resetting a user's password description: |- The homeserver must check that the given email address **is associated** with an account on this homeserver. This API should be @@ -430,46 +459,55 @@ paths: The homeserver should validate the email itself, either by sending a validation email itself or by using a service it has control over. operationId: requestTokenToResetPasswordEmail - parameters: - - in: body - name: body - required: true - schema: - $ref: "definitions/request_email_validation.yaml" + requestBody: + content: + application/json: + schema: + $ref: definitions/request_email_validation.yaml + required: true responses: - 200: + "200": description: An email was sent to the given address. - schema: - $ref: "definitions/request_token_response.yaml" - 403: - description: |- - The homeserver does not allow the third-party identifier as a - contact option. - schema: - $ref: "definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_THREEPID_DENIED", - "error": "Third-party identifier is not allowed" - } - 400: + content: + application/json: + schema: + $ref: definitions/request_token_response.yaml + "400": description: |- The referenced third-party identifier is not recognised by the homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED` can be returned if the server does not trust/support the identity server provided in the request. - schema: - $ref: "definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_THREEPID_NOT_FOUND", - "error": "Email not found" - } + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_NOT_FOUND", + "error": "Email not found" + } + "403": + description: |- + The homeserver does not allow the third-party identifier as a + contact option. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_DENIED", + "error": "Third-party identifier is not allowed" + } tags: - Account management - "/account/password/msisdn/requestToken": + /account/password/msisdn/requestToken: post: - summary: Requests a validation token be sent to the given phone number for the purpose of resetting a user's password. + summary: Requests a validation token be sent to the given phone number for the + purpose of resetting a user's password. description: |- The homeserver must check that the given phone number **is associated** with an account on this homeserver. This API should be @@ -487,46 +525,54 @@ paths: The homeserver should validate the phone number itself, either by sending a validation message itself or by using a service it has control over. operationId: requestTokenToResetPasswordMSISDN - parameters: - - in: body - name: body - required: true - schema: - $ref: "definitions/request_msisdn_validation.yaml" + requestBody: + content: + application/json: + schema: + $ref: definitions/request_msisdn_validation.yaml + required: true responses: - 200: + "200": description: An SMS message was sent to the given phone number. - schema: - $ref: "definitions/request_token_response.yaml" - 403: - description: |- - The homeserver does not allow the third-party identifier as a - contact option. - schema: - $ref: "definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_THREEPID_DENIED", - "error": "Third-party identifier is not allowed" - } - 400: + content: + application/json: + schema: + $ref: definitions/request_token_response.yaml + "400": description: |- The referenced third-party identifier is not recognised by the homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED` can be returned if the server does not trust/support the identity server provided in the request. - schema: - $ref: "definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_THREEPID_NOT_FOUND", - "error": "Phone number not found" - } + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_NOT_FOUND", + "error": "Phone number not found" + } + "403": + description: |- + The homeserver does not allow the third-party identifier as a + contact option. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_DENIED", + "error": "Third-party identifier is not allowed" + } tags: - Account management - "/account/deactivate": + /account/deactivate: post: - summary: "Deactivate a user's account." + summary: Deactivate a user's account. description: |- Deactivate the user's account, removing all ability for the user to login again. @@ -545,63 +591,68 @@ paths: security: - accessToken: [] operationId: deactivateAccount - parameters: - - in: body - name: body - required: true - schema: - type: object - properties: - auth: - description: |- - Additional authentication information for the user-interactive authentication API. - allOf: - - $ref: "definitions/auth_data.yaml" - id_server: - type: string - description: |- - The identity server to unbind all of the user's 3PIDs from. - If not provided, the homeserver MUST use the `id_server` - that was originally use to bind each identifier. If the - homeserver does not know which `id_server` that was, - it must return an `id_server_unbind_result` of - `no-support`. - example: "example.org" + requestBody: + content: + application/json: + schema: + type: object + properties: + auth: + description: Additional authentication information for the user-interactive + authentication API. + allOf: + - $ref: definitions/auth_data.yaml + id_server: + type: string + description: |- + The identity server to unbind all of the user's 3PIDs from. + If not provided, the homeserver MUST use the `id_server` + that was originally use to bind each identifier. If the + homeserver does not know which `id_server` that was, + it must return an `id_server_unbind_result` of + `no-support`. + example: example.org + required: true responses: - 200: + "200": description: The account has been deactivated. - schema: - type: object - properties: - id_server_unbind_result: - type: string - enum: - - "success" - - "no-support" - description: |- - An indicator as to whether or not the homeserver was able to unbind - the user's 3PIDs from the identity server(s). `success` indicates - that all identifiers have been unbound from the identity server while - `no-support` indicates that one or more identifiers failed to unbind - due to the identity server refusing the request or the homeserver - being unable to determine an identity server to unbind from. This - must be `success` if the homeserver has no identifiers to unbind - for the user. - example: "success" - required: - - id_server_unbind_result - 401: - description: |- - The homeserver requires additional authentication information. - schema: - "$ref": "definitions/auth_response.yaml" - 429: + content: + application/json: + schema: + type: object + properties: + id_server_unbind_result: + type: string + enum: + - success + - no-support + description: |- + An indicator as to whether or not the homeserver was able to unbind + the user's 3PIDs from the identity server(s). `success` indicates + that all identifiers have been unbound from the identity server while + `no-support` indicates that one or more identifiers failed to unbind + due to the identity server refusing the request or the homeserver + being unable to determine an identity server to unbind from. This + must be `success` if the homeserver has no identifiers to unbind + for the user. + example: success + required: + - id_server_unbind_result + "401": + description: The homeserver requires additional authentication information. + content: + application/json: + schema: + $ref: definitions/auth_response.yaml + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Account management - "/register/available": + /register/available: get: summary: Checks to see if a username is available on the server. description: |- @@ -621,27 +672,31 @@ paths: parameters: - in: query name: username - type: string - x-example: my_cool_localpart required: true - default: my_cool_localpart description: The username to check the availability of. + example: my_cool_localpart + schema: + type: string + default: my_cool_localpart responses: - 200: + "200": description: The username is available - examples: - application/json: { - "available": true - } - schema: - type: object - properties: - available: - type: boolean - description: |- - A flag to indicate that the username is available. This should always - be `true` when the server replies with 200 OK. - 400: + content: + application/json: + schema: + type: object + properties: + available: + type: boolean + description: |- + A flag to indicate that the username is available. This should always + be `true` when the server replies with 200 OK. + examples: + response: + value: { + "available": true + } + "400": description: |- Part of the request was invalid or the username is not available. This may include one of the following error codes: @@ -650,16 +705,33 @@ paths: * `M_INVALID_USERNAME` : The desired username is not a valid user name. * `M_EXCLUSIVE` : The desired username is in the exclusive namespace claimed by an application service. - examples: - application/json: { - "errcode": "M_USER_IN_USE", - "error": "Desired user ID is already taken." - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_USER_IN_USE", + "error": "Desired user ID is already taken." + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Account management +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 diff --git a/data/api/client-server/registration_tokens.yaml b/data/api/client-server/registration_tokens.yaml index 11241b573..9468a0bb0 100644 --- a/data/api/client-server/registration_tokens.yaml +++ b/data/api/client-server/registration_tokens.yaml @@ -11,21 +11,12 @@ # 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 Registration Token API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v1 -consumes: - - application/json -produces: - - application/json + title: Matrix Client-Server Registration Token API + version: 1.0.0 paths: - "/register/m.login.registration_token/validity": + /register/m.login.registration_token/validity: get: x-addedInMatrixVersion: "1.2" summary: Query if a given registration token is still valid. @@ -40,41 +31,63 @@ paths: parameters: - in: query name: token - type: string - x-example: "fBVFdqVE" required: true description: The token to check validity of. + example: fBVFdqVE + schema: + type: string responses: - 200: + "200": description: The check has a result. - examples: - application/json: { - "valid": true - } - schema: - type: object - properties: - valid: - type: boolean - description: |- - True if the token is still valid, false otherwise. This should - additionally be false if the token is not a recognised token by - the server. - required: ['valid'] - 403: + content: + application/json: + schema: + type: object + properties: + valid: + type: boolean + description: |- + True if the token is still valid, false otherwise. This should + additionally be false if the token is not a recognised token by + the server. + required: + - valid + examples: + response: + value: { + "valid": true + } + "403": description: |- The homeserver does not permit registration and thus all tokens are considered invalid. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "Registration is not enabled on this homeserver." - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "Registration is not enabled on this homeserver." + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Account management +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v1 diff --git a/data/api/client-server/relations.yaml b/data/api/client-server/relations.yaml index a0abae1bd..f773c39b6 100644 --- a/data/api/client-server/relations.yaml +++ b/data/api/client-server/relations.yaml @@ -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 Relations API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Relations API + version: 1.0.0 paths: "/rooms/{roomId}/relations/{eventId}": get: @@ -45,19 +34,20 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The ID of the room containing the parent event. required: true - x-example: "!636q39766251:matrix.org" + example: "!636q39766251:matrix.org" + schema: + type: string - in: path - type: string name: eventId description: The ID of the parent event whose child events are to be returned. required: true - x-example: "$asfDuShaf7Gafaw" + example: $asfDuShaf7Gafaw + schema: + type: string - in: query - type: string name: from description: |- The pagination token to start returning results from. If not supplied, results @@ -67,9 +57,10 @@ paths: `start` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages), or a `next_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync). required: false - x-example: "page2_token" + example: page2_token + schema: + type: string - in: query - type: string name: to description: |- The pagination token to stop returning results at. If not supplied, results @@ -78,9 +69,10 @@ paths: Like `from`, this can be a previous token from a prior call to this endpoint or from `/messages` or `/sync`. required: false - x-example: "page3_token" + example: page3_token + schema: + type: string - in: query - type: integer name: limit description: |- The maximum number of results to return in a single `chunk`. The server can @@ -88,10 +80,10 @@ paths: Similarly, the server should apply a default value when not supplied. required: false - x-example: 20 + example: 20 + schema: + type: integer - in: query - type: string - enum: ["b", "f"] name: dir x-addedInMatrixVersion: "1.4" description: |- @@ -99,66 +91,76 @@ paths: will be returned in chronological order starting at `from`. If it is set to `b`, events will be returned in *reverse* chronological order, again starting at `from`. + schema: + type: string + enum: + - b + - f responses: - # note: this endpoint deliberately does not support rate limiting, therefore a - # 429 error response is not included. - - 200: + "200": description: |- The paginated child events which point to the parent. If no events are pointing to the parent or the pagination yields no results, an empty `chunk` is returned. - examples: - application/json: { - "chunk": [{ - "room_id": "!636q39766251:matrix.org", - "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml", - "content": { - "m.relates_to": { - "rel_type": "org.example.my_relation", - "event_id": "$asfDuShaf7Gafaw" + content: + application/json: + schema: + type: object + properties: + chunk: + title: ChildEventsChunk + type: array + description: The child events of the requested event, ordered topologically + most-recent first. + items: + allOf: + - $ref: definitions/client_event.yaml + next_batch: + type: string + description: |- + An opaque string representing a pagination token. The absence of this token + means there are no more results to fetch and the client should stop paginating. + prev_batch: + type: string + description: |- + An opaque string representing a pagination token. The absence of this token + means this is the start of the result set, i.e. this is the first batch/page. + required: + - chunk + examples: + response: + value: { + "chunk": [ + { + "room_id": "!636q39766251:matrix.org", + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml", + "content": { + "m.relates_to": { + "rel_type": "org.example.my_relation", + "event_id": "$asfDuShaf7Gafaw" + } + } + } + ], + "next_batch": "page2_token", + "prev_batch": "page1_token" } - } - }], - "next_batch": "page2_token", - "prev_batch": "page1_token" - } - schema: - type: object - properties: - chunk: - title: "ChildEventsChunk" - type: array - description: |- - The child events of the requested event, ordered topologically most-recent first. - items: - allOf: - - "$ref": "definitions/client_event.yaml" - next_batch: - type: string - description: |- - An opaque string representing a pagination token. The absence of this token - means there are no more results to fetch and the client should stop paginating. - prev_batch: - type: string - description: |- - An opaque string representing a pagination token. The absence of this token - means this is the start of the result set, i.e. this is the first batch/page. - required: ['chunk'] - 404: + "404": description: |- The parent event was not found or the user does not have permission to read this event (it might be contained in history that is not accessible to the user). - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Event not found." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Event not found." + } tags: - Event relationships - # The same as above, with added `/{relType}` "/rooms/{roomId}/relations/{eventId}/{relType}": get: summary: Get the child events for a given parent event, with a given `relType`. @@ -178,26 +180,28 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The ID of the room containing the parent event. required: true - x-example: "!636q39766251:matrix.org" + example: "!636q39766251:matrix.org" + schema: + type: string - in: path - type: string name: eventId description: The ID of the parent event whose child events are to be returned. required: true - x-example: "$asfDuShaf7Gafaw" + example: $asfDuShaf7Gafaw + schema: + type: string - in: path - type: string name: relType - description: |- - The [relationship type](/client-server-api/#relationship-types) to search for. + description: The [relationship type](/client-server-api/#relationship-types) to + search for. required: true - x-example: "org.example.my_relation" + example: org.example.my_relation + schema: + type: string - in: query - type: string name: from description: |- The pagination token to start returning results from. If not supplied, results @@ -207,9 +211,10 @@ paths: `start` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages), or a `next_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync). required: false - x-example: "page2_token" + example: page2_token + schema: + type: string - in: query - type: string name: to description: |- The pagination token to stop returning results at. If not supplied, results @@ -218,9 +223,10 @@ paths: Like `from`, this can be a previous token from a prior call to this endpoint or from `/messages` or `/sync`. required: false - x-example: "page3_token" + example: page3_token + schema: + type: string - in: query - type: integer name: limit description: |- The maximum number of results to return in a single `chunk`. The server can @@ -228,10 +234,10 @@ paths: Similarly, the server should apply a default value when not supplied. required: false - x-example: 20 + example: 20 + schema: + type: integer - in: query - type: string - enum: ["b", "f"] name: dir x-addedInMatrixVersion: "1.4" description: |- @@ -239,71 +245,82 @@ paths: will be returned in chronological order starting at `from`. If it is set to `b`, events will be returned in *reverse* chronological order, again starting at `from`. + schema: + type: string + enum: + - b + - f responses: - # note: this endpoint deliberately does not support rate limiting, therefore a - # 429 error response is not included. - - 200: + "200": description: |- The paginated child events which point to the parent. If no events are pointing to the parent or the pagination yields no results, an empty `chunk` is returned. - examples: - application/json: { - "chunk": [{ - "room_id": "!636q39766251:matrix.org", - "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml", - "content": { - "m.relates_to": { - "rel_type": "org.example.my_relation", - "event_id": "$asfDuShaf7Gafaw" + content: + application/json: + schema: + type: object + properties: + chunk: + title: ChildEventsChunk + type: array + description: |- + The child events of the requested event, ordered topologically + most-recent first. The events returned will match the `relType` + supplied in the URL. + items: + allOf: + - $ref: definitions/client_event.yaml + next_batch: + type: string + description: |- + An opaque string representing a pagination token. The absence of this token + means there are no more results to fetch and the client should stop paginating. + prev_batch: + type: string + description: |- + An opaque string representing a pagination token. The absence of this token + means this is the start of the result set, i.e. this is the first batch/page. + required: + - chunk + examples: + response: + value: { + "chunk": [ + { + "room_id": "!636q39766251:matrix.org", + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml", + "content": { + "m.relates_to": { + "rel_type": "org.example.my_relation", + "event_id": "$asfDuShaf7Gafaw" + } + } + } + ], + "next_batch": "page2_token", + "prev_batch": "page1_token" } - } - }], - "next_batch": "page2_token", - "prev_batch": "page1_token" - } - schema: - type: object - properties: - chunk: - title: "ChildEventsChunk" - type: array - description: |- - The child events of the requested event, ordered topologically - most-recent first. The events returned will match the `relType` - supplied in the URL. - items: - allOf: - - "$ref": "definitions/client_event.yaml" - next_batch: - type: string - description: |- - An opaque string representing a pagination token. The absence of this token - means there are no more results to fetch and the client should stop paginating. - prev_batch: - type: string - description: |- - An opaque string representing a pagination token. The absence of this token - means this is the start of the result set, i.e. this is the first batch/page. - required: ['chunk'] - 404: + "404": description: |- The parent event was not found or the user does not have permission to read this event (it might be contained in history that is not accessible to the user). - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Event not found." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Event not found." + } tags: - Event relationships - # The same as above, with added `/{eventType}` "/rooms/{roomId}/relations/{eventId}/{relType}/{eventType}": get: - summary: Get the child events for a given parent event, with a given `relType` and `eventType`. + summary: Get the child events for a given parent event, with a given `relType` + and `eventType`. description: |- Retrieve all of the child events for a given parent event which relate to the parent using the given `relType` and have the given `eventType`. @@ -320,26 +337,28 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The ID of the room containing the parent event. required: true - x-example: "!636q39766251:matrix.org" + example: "!636q39766251:matrix.org" + schema: + type: string - in: path - type: string name: eventId description: The ID of the parent event whose child events are to be returned. required: true - x-example: "$asfDuShaf7Gafaw" + example: $asfDuShaf7Gafaw + schema: + type: string - in: path - type: string name: relType - description: |- - The [relationship type](/client-server-api/#relationship-types) to search for. + description: The [relationship type](/client-server-api/#relationship-types) to + search for. required: true - x-example: "org.example.my_relation" + example: org.example.my_relation + schema: + type: string - in: path - type: string name: eventType description: |- The event type of child events to search for. @@ -347,9 +366,10 @@ paths: Note that in encrypted rooms this will typically always be `m.room.encrypted` regardless of the event type contained within the encrypted payload. required: true - x-example: "m.room.message" + example: m.room.message + schema: + type: string - in: query - type: string name: from description: |- The pagination token to start returning results from. If not supplied, results @@ -359,9 +379,10 @@ paths: `start` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages), or a `next_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync). required: false - x-example: "page2_token" + example: page2_token + schema: + type: string - in: query - type: string name: to description: |- The pagination token to stop returning results at. If not supplied, results @@ -370,9 +391,10 @@ paths: Like `from`, this can be a previous token from a prior call to this endpoint or from `/messages` or `/sync`. required: false - x-example: "page3_token" + example: page3_token + schema: + type: string - in: query - type: integer name: limit description: |- The maximum number of results to return in a single `chunk`. The server can @@ -380,10 +402,10 @@ paths: Similarly, the server should apply a default value when not supplied. required: false - x-example: 20 + example: 20 + schema: + type: integer - in: query - type: string - enum: ["b", "f"] name: dir x-addedInMatrixVersion: "1.4" description: |- @@ -391,65 +413,90 @@ paths: will be returned in chronological order starting at `from`. If it is set to `b`, events will be returned in *reverse* chronological order, again starting at `from`. + schema: + type: string + enum: + - b + - f responses: - # note: this endpoint deliberately does not support rate limiting, therefore a - # 429 error response is not included. - - 200: + "200": description: |- The paginated child events which point to the parent. If no events are pointing to the parent or the pagination yields no results, an empty `chunk` is returned. - examples: - application/json: { - "chunk": [{ - "room_id": "!636q39766251:matrix.org", - "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml", - "content": { - "m.relates_to": { - "rel_type": "org.example.my_relation", - "event_id": "$asfDuShaf7Gafaw" + content: + application/json: + schema: + type: object + properties: + chunk: + title: ChildEventsChunk + type: array + description: |- + The child events of the requested event, ordered topologically most-recent + first. The events returned will match the `relType` and `eventType` supplied + in the URL. + items: + allOf: + - $ref: definitions/client_event.yaml + next_batch: + type: string + description: |- + An opaque string representing a pagination token. The absence of this token + means there are no more results to fetch and the client should stop paginating. + prev_batch: + type: string + description: |- + An opaque string representing a pagination token. The absence of this token + means this is the start of the result set, i.e. this is the first batch/page. + required: + - chunk + examples: + response: + value: { + "chunk": [ + { + "room_id": "!636q39766251:matrix.org", + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml", + "content": { + "m.relates_to": { + "rel_type": "org.example.my_relation", + "event_id": "$asfDuShaf7Gafaw" + } + } + } + ], + "next_batch": "page2_token", + "prev_batch": "page1_token" } - } - }], - "next_batch": "page2_token", - "prev_batch": "page1_token" - } - schema: - type: object - properties: - chunk: - title: "ChildEventsChunk" - type: array - description: |- - The child events of the requested event, ordered topologically most-recent - first. The events returned will match the `relType` and `eventType` supplied - in the URL. - items: - allOf: - - "$ref": "definitions/client_event.yaml" - next_batch: - type: string - description: |- - An opaque string representing a pagination token. The absence of this token - means there are no more results to fetch and the client should stop paginating. - prev_batch: - type: string - description: |- - An opaque string representing a pagination token. The absence of this token - means this is the start of the result set, i.e. this is the first batch/page. - required: ['chunk'] - 404: + "404": description: |- The parent event was not found or the user does not have permission to read this event (it might be contained in history that is not accessible to the user). - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Event not found." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Event not found." + } tags: - Event relationships - +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/report_content.yaml b/data/api/client-server/report_content.yaml index 7f8b3425c..5ea7b6348 100644 --- a/data/api/client-server/report_content.yaml +++ b/data/api/client-server/report_content.yaml @@ -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 Report Content 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 Report Content API + version: 1.0.0 paths: "/rooms/{roomId}/report/{eventId}": post: @@ -36,43 +25,64 @@ paths: operationId: reportContent parameters: - in: path - type: string name: roomId description: The room in which the event being reported is located. required: true - x-example: "!637q39766251:example.com" + example: "!637q39766251:example.com" + schema: + type: string - in: path - type: string name: eventId description: The event to report. required: true - x-example: "$something:example.org" - - in: body - name: body - required: true + example: $something:example.org schema: - type: object - example: { - "score": -100, - "reason": "this makes me sad" - } - properties: - score: - type: integer - description: |- - The score to rate this content as where -100 is most offensive - and 0 is inoffensive. - reason: - type: string - description: The reason the content is being reported. May be blank. + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { + "score": -100, + "reason": "this makes me sad" + } + properties: + score: + type: integer + description: |- + The score to rate this content as where -100 is most offensive + and 0 is inoffensive. + reason: + type: string + description: The reason the content is being reported. May be blank. + required: true security: - accessToken: [] responses: - 200: + "200": description: The event has been reported successfully. - schema: - type: object - examples: - application/json: {} + content: + application/json: + schema: + type: object + examples: + response: + value: {} tags: - Reporting content +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 diff --git a/data/api/client-server/room_event_by_timestamp.yaml b/data/api/client-server/room_event_by_timestamp.yaml index 7b3609215..19e7302b8 100644 --- a/data/api/client-server/room_event_by_timestamp.yaml +++ b/data/api/client-server/room_event_by_timestamp.yaml @@ -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 events in room by date API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server events in room by date API + version: 1.0.0 paths: "/rooms/{roomId}/timestamp_to_event": get: @@ -60,64 +49,91 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The ID of the room to search required: true - x-example: "!636q39766251:matrix.org" + example: "!636q39766251:matrix.org" + schema: + type: string - in: query - type: integer name: ts description: |- The timestamp to search from, as given in milliseconds since the Unix epoch. required: true - x-example: 1432684800000 + example: 1432684800000 + schema: + type: integer - in: query - type: string - enum: [f, b] name: dir - description: |- - The direction in which to search. `f` for forwards, `b` for backwards. + description: The direction in which to search. `f` for forwards, `b` for + backwards. required: true - x-example: f - responses: - 200: - description: |- - An event was found matching the search parameters. + example: f schema: - type: object - properties: - event_id: - type: string - description: |- - The ID of the event found - origin_server_ts: - type: integer - description: |- - The event's timestamp, in milliseconds since the Unix epoch. - This makes it easy to do a quick comparison to see if the - `event_id` fetched is too far out of range to be useful for your - use case. - required: ['event_id', 'origin_server_ts'] - examples: - application/json: { - "event_id": "$143273582443PhrSn:example.org", - "origin_server_ts": 1432735824653 - } - 404: - description: |- - No event was found. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Unable to find event from 1432684800000 in forward direction" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + type: string + enum: + - f + - b + responses: + "200": + description: An event was found matching the search parameters. + content: + application/json: + schema: + type: object + properties: + event_id: + type: string + description: The ID of the event found + origin_server_ts: + type: integer + description: |- + The event's timestamp, in milliseconds since the Unix epoch. + This makes it easy to do a quick comparison to see if the + `event_id` fetched is too far out of range to be useful for your + use case. + required: + - event_id + - origin_server_ts + examples: + response: + value: { + "event_id": "$143273582443PhrSn:example.org", + "origin_server_ts": 1432735824653 + } + "404": + description: No event was found. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Unable to find event from 1432684800000 in forward direction" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Room participation +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/room_initial_sync.yaml b/data/api/client-server/room_initial_sync.yaml index 64e7f4f20..53cb0beea 100644 --- a/data/api/client-server/room_initial_sync.yaml +++ b/data/api/client-server/room_initial_sync.yaml @@ -1,18 +1,7 @@ -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}/initialSync": get: @@ -29,127 +18,161 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room to get the data. required: true - x-example: "!636q39766251:example.com" + example: "!636q39766251:example.com" + schema: + type: string responses: - 200: + "200": description: The current state of the room - examples: - application/json: { - "membership": "join", - "messages": { - "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.message$m.file.yaml" - } - ], - "end": "s3456_9_0", - "start": "t44-3453_9_0" - }, - "room_id": "!636q39766251:example.com", - "state": [ - { - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.join_rules.yaml" - }, - { - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.member.yaml" - }, - { - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.create.yaml" - }, - { - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.power_levels.yaml" - } - ], - "visibility": "private", - "account_data": [{ - "type": "m.tag", - "content": {"tags": {"work": {"order": "1"}}} - }] - } - schema: - title: RoomInfo - type: object - properties: - room_id: - type: string - description: "The ID of this room." - membership: - type: string - description: "The user's membership state in this room." - enum: ["invite", "join", "leave", "ban"] - messages: + content: + application/json: + schema: + title: RoomInfo type: object - title: PaginationChunk - description: "The pagination chunk for this room." properties: - start: + room_id: type: string - description: |- - A token which correlates to the start of `chunk`. Can be passed to - [`/rooms//messages`](#get_matrixclientv3roomsroomidmessages) - to retrieve earlier events. + description: The ID of this room. + membership: + type: string + description: The user's membership state in this room. + enum: + - invite + - join + - leave + - ban + messages: + type: object + title: PaginationChunk + description: The pagination chunk for this room. + properties: + start: + type: string + description: |- + A token which correlates to the start of `chunk`. Can be passed to + [`/rooms//messages`](#get_matrixclientv3roomsroomidmessages) + to retrieve earlier events. - If no earlier events are available, this property may be omitted from - the response. - end: + If no earlier events are available, this property may be omitted from + the response. + end: + type: string + description: |- + A token which correlates to the end of `chunk`. Can be passed to + [`/rooms//messages`](#get_matrixclientv3roomsroomidmessages) + to retrieve later events. + chunk: + type: array + description: |- + If the user is a member of the room this will be a + list of the most recent messages for this room. If + the user has left the room this will be the + messages that preceded them leaving. This array + will consist of at most `limit` elements. + items: + $ref: definitions/client_event.yaml + required: + - end + - chunk + state: + type: array + description: |- + If the user is a member of the room this will be the + current state of the room as a list of events. If the + user has left the room this will be the state of the + room when they left it. + items: + $ref: definitions/client_event.yaml + visibility: type: string + enum: + - private + - public description: |- - A token which correlates to the end of `chunk`. Can be passed to - [`/rooms//messages`](#get_matrixclientv3roomsroomidmessages) - to retrieve later events. - chunk: + Whether this room is visible to the `/publicRooms` API + or not." + account_data: type: array - description: |- - If the user is a member of the room this will be a - list of the most recent messages for this room. If - the user has left the room this will be the - messages that preceded them leaving. This array - will consist of at most `limit` elements. + description: The private data that this user has attached to this room. items: - "$ref": "definitions/client_event.yaml" - required: ["end", "chunk"] - state: - type: array - description: |- - If the user is a member of the room this will be the - current state of the room as a list of events. If the - user has left the room this will be the state of the - room when they left it. - items: - "$ref": "definitions/client_event.yaml" - visibility: - type: string - enum: ["private", "public"] - description: |- - Whether this room is visible to the `/publicRooms` API - or not." - account_data: - type: array - description: |- - The private data that this user has attached to this room. - items: - title: Event - type: object - allOf: - - "$ref": "../../event-schemas/schema/core-event-schema/event.yaml" - required: ["room_id"] - 403: - description: > - You aren't a member of the room and weren't previously a - member of the room. + title: Event + type: object + allOf: + - $ref: ../../event-schemas/schema/core-event-schema/event.yaml + required: + - room_id + examples: + response: + value: { + "membership": "join", + "messages": { + "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.message$m.file.yaml" + } + ], + "end": "s3456_9_0", + "start": "t44-3453_9_0" + }, + "room_id": "!636q39766251:example.com", + "state": [ + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.join_rules.yaml" + }, + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.member.yaml" + }, + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.create.yaml" + }, + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.power_levels.yaml" + } + ], + "visibility": "private", + "account_data": [ + { + "type": "m.tag", + "content": { + "tags": { + "work": { + "order": "1" + } + } + } + } + ] + } + "403": + description: | + You aren't a member of the room and weren't previously a member of the room. tags: - Room participation deprecated: true +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 diff --git a/data/api/client-server/room_send.yaml b/data/api/client-server/room_send.yaml index 43823c453..638dc86d5 100644 --- a/data/api/client-server/room_send.yaml +++ b/data/api/client-server/room_send.yaml @@ -12,21 +12,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 message event send 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 message event send API + version: 1.0.0 paths: "/rooms/{roomId}/send/{eventType}/{txnId}": put: @@ -44,58 +33,81 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room to send the event to. required: true - x-example: "!636q39766251:example.com" + example: "!636q39766251:example.com" + schema: + type: string - in: path - type: string name: eventType description: The type of event to send. required: true - x-example: "m.room.message" + example: m.room.message + schema: + type: string - in: path name: txnId - type: string description: |- The [transaction ID](/client-server-api/#transaction-identifiers) for this event. Clients should generate an ID unique across requests with the same access token; it will be used by the server to ensure idempotency of requests. required: true - x-example: "35" - - in: body - name: body - required: true + example: "35" schema: - type: object - example: { + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { "msgtype": "m.text", "body": "hello" } + required: true responses: - 200: - description: "An ID for the sent event." - examples: - application/json: { - "event_id": "$YUwRidLecu:example.com" - } - schema: - type: object - properties: - event_id: - type: string - description: |- - A unique identifier for the event. - required: - - event_id - 400: + "200": + description: An ID for the sent event. + content: + application/json: + schema: + type: object + properties: + event_id: + type: string + description: A unique identifier for the event. + required: + - event_id + examples: + response: + value: { + "event_id": "$YUwRidLecu:example.com" + } + "400": description: |- The request is invalid. A [standard error response](/client-server-api/#standard-error-response) will be returned. As well as the normal common error codes, other reasons for rejection include: - `M_DUPLICATE_ANNOTATION`: The request is an attempt to send a [duplicate annotation](/client-server-api/#avoiding-duplicate-annotations). - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml 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 diff --git a/data/api/client-server/room_state.yaml b/data/api/client-server/room_state.yaml index d43bc8027..1c03dbddd 100644 --- a/data/api/client-server/room_state.yaml +++ b/data/api/client-server/room_state.yaml @@ -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 state event send 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 state event send API + version: 1.0.0 paths: "/rooms/{roomId}/state/{eventType}/{stateKey}": put: @@ -53,62 +42,58 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room to set the state in required: true - x-example: "!636q39766251:example.com" + example: "!636q39766251:example.com" + schema: + type: string - in: path - type: string name: eventType description: The type of event to send. required: true - x-example: "m.room.member" + example: m.room.member + schema: + type: string - in: path - type: string name: stateKey description: |- The state_key for the state to send. Defaults to the empty string. When an empty string, the trailing slash on this endpoint is optional. required: true - x-example: "@alice:example.com" - - in: body - name: body - required: true + example: "@alice:example.com" schema: - type: object - example: { + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { "membership": "join", "avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF", "displayname": "Alice Margatroid" } + required: true responses: - 200: - description: "An ID for the sent event." - examples: - application/json: { - "event_id": "$YUwRidLecu:example.com" - } - schema: - type: object - properties: - event_id: - type: string - description: |- - A unique identifier for the event. - required: - - event_id - 403: - description: |- - The sender doesn't have permission to send the event into the room. - schema: - $ref: "definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "You do not have permission to send the event." - } - 400: + "200": + description: An ID for the sent event. + content: + application/json: + schema: + type: object + properties: + event_id: + type: string + description: A unique identifier for the event. + required: + - event_id + examples: + response: + value: { + "event_id": "$YUwRidLecu:example.com" + } + "400": description: |- The sender's request is malformed. @@ -119,12 +104,42 @@ paths: * `M_BAD_ALIAS`: One or more aliases within the `m.room.canonical_alias` event do not point to the room ID for which the state event is to be sent to. - schema: - $ref: "definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_BAD_ALIAS", - "error": "The alias '#hello:example.org' does not point to this room." - } + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_BAD_ALIAS", + "error": "The alias '#hello:example.org' does not point to this room." + } + "403": + description: The sender doesn't have permission to send the event into the room. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You do not have permission to send the event." + } 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 diff --git a/data/api/client-server/room_upgrades.yaml b/data/api/client-server/room_upgrades.yaml index 41b3a7af1..296ffe6a4 100644 --- a/data/api/client-server/room_upgrades.yaml +++ b/data/api/client-server/room_upgrades.yaml @@ -11,82 +11,99 @@ # 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 Room Upgrades 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 Room Upgrades API + version: 1.0.0 paths: "/rooms/{roomId}/upgrade": post: summary: Upgrades a room to a new room version. - description: |- - Upgrades the given room to a particular room version. + description: Upgrades the given room to a particular room version. operationId: upgradeRoom security: - accessToken: [] parameters: - in: path - type: string name: roomId required: true description: The ID of the room to upgrade. - x-example: "!oldroom:example.org" - - in: body - name: body - required: true + example: "!oldroom:example.org" schema: - type: object - properties: - new_version: - type: string - description: The new version for the room. - example: {"new_version": "2"} - required: [new_version] + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + new_version: + type: string + description: The new version for the room. + example: { + "new_version": "2" + } + required: + - new_version + required: true responses: - 200: + "200": description: The room was successfully upgraded. - examples: - application/json: { - "replacement_room": "!newroom:example.org" - } - schema: - type: object - properties: - replacement_room: - type: string - description: The ID of the new room. - required: [replacement_room] - 400: + content: + application/json: + schema: + type: object + properties: + replacement_room: + type: string + description: The ID of the new room. + required: + - replacement_room + examples: + response: + value: { + "replacement_room": "!newroom:example.org" + } + "400": description: |- The request was invalid. One way this can happen is if the room version requested is not supported by the homeserver. - examples: - application/json: { - "errcode": "M_UNSUPPORTED_ROOM_VERSION", - "error": "This server does not support that room version" - } - schema: - "$ref": "definitions/errors/error.yaml" - 403: - description: |- - The user is not permitted to upgrade the room. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "You cannot upgrade this room" - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_UNSUPPORTED_ROOM_VERSION", + "error": "This server does not support that room version" + } + "403": + description: The user is not permitted to upgrade the room. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You cannot upgrade this room" + } tags: - Room upgrades +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 diff --git a/data/api/client-server/rooms.yaml b/data/api/client-server/rooms.yaml index 2ee3fa191..15a0fea12 100644 --- a/data/api/client-server/rooms.yaml +++ b/data/api/client-server/rooms.yaml @@ -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}/event/{eventId}": get: @@ -38,36 +27,45 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The ID of the room the event is in. required: true - x-example: "!636q39766251:matrix.org" + example: "!636q39766251:matrix.org" + schema: + type: string - in: path - type: string name: eventId description: The event ID to get. required: true - x-example: "$asfDuShaf7Gafaw:matrix.org" + example: $asfDuShaf7Gafaw:matrix.org + schema: + type: string responses: - 200: + "200": description: The full event. - examples: - application/json: { - "room_id": "!636q39766251:matrix.org", - "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" - } - schema: - "$ref": "definitions/client_event.yaml" - 404: - description: The event was not found or you do not have permission to read this event. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Event not found." - } - schema: - "$ref": "definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: definitions/client_event.yaml + examples: + response: + value: { + "room_id": "!636q39766251:matrix.org", + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + } + "404": + description: The event was not found or you do not have permission to read this + event. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Event not found." + } tags: - Room participation "/rooms/{roomId}/state/{eventType}/{stateKey}": @@ -83,225 +81,257 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room to look up the state in. required: true - x-example: "!636q39766251:example.com" + example: "!636q39766251:example.com" + schema: + type: string - in: path - type: string name: eventType description: The type of state to look up. required: true - x-example: "m.room.name" + example: m.room.name + schema: + type: string - in: path - type: string name: stateKey description: |- The key of the state to look up. Defaults to an empty string. When an empty string, the trailing slash on this endpoint is optional. required: true - x-example: "" + example: "" + schema: + type: string responses: - 200: + "200": description: The content of the state event. - examples: - application/json: { - "name": "Example room name"} - schema: - type: object - 404: + content: + application/json: + schema: + type: object + examples: + response: + value: { + "name": "Example room name" + } + "403": + description: | + You aren't a member of the room and weren't previously a member of the room. + "404": description: The room has no state with the given type or key. - 403: - description: > - You aren't a member of the room and weren't previously a - member of the room. tags: - Room participation "/rooms/{roomId}/state": get: summary: Get all state events in the current state of a room. - description: |- - Get the state events for the current state of a room. + description: Get the state events for the current state of a room. operationId: getRoomState security: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room to look up the state for. required: true - x-example: "!636q39766251:example.com" + example: "!636q39766251:example.com" + schema: + type: string responses: - 200: + "200": description: The current state of the room - examples: - application/json: [ - { - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.join_rules.yaml" - }, - { - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.member.yaml" - }, - { - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.create.yaml" - }, - { - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.power_levels.yaml" - } - ] - schema: - type: array - title: RoomState - description: |- - If the user is a member of the room this will be the - current state of the room as a list of events. If the user - has left the room then this will be the state of the room - when they left as a list of events. - items: - $ref: "definitions/client_event.yaml" - 403: - description: > - You aren't a member of the room and weren't previously a - member of the room. + content: + application/json: + schema: + type: array + title: RoomState + description: |- + If the user is a member of the room this will be the + current state of the room as a list of events. If the user + has left the room then this will be the state of the room + when they left as a list of events. + items: + $ref: definitions/client_event.yaml + examples: + response: + value: [ + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.join_rules.yaml" + }, + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.member.yaml" + }, + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.create.yaml" + }, + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.power_levels.yaml" + } + ] + "403": + description: | + You aren't a member of the room and weren't previously a member of the room. tags: - Room participation "/rooms/{roomId}/members": get: summary: Get the m.room.member events for the room. - description: - Get the list of members for this room. + description: Get the list of members for this room. operationId: getMembersByRoom parameters: - in: path - type: string name: roomId description: The room to get the member events for. required: true - x-example: "!636q39766251:example.com" + example: "!636q39766251:example.com" + schema: + type: string - in: query name: at - type: string description: |- The point in time (pagination token) to return members for in the room. This token can be obtained from a `prev_batch` token returned for each room by the sync API. Defaults to the current state of the room, as determined by the server. - x-example: "YWxsCgpOb25lLDM1ODcwOA" - # XXX: As mentioned in MSC1227, replacing `[not_]membership` with a JSON - # filter might be a better alternative. - # See https://github.com/matrix-org/matrix-doc/issues/1337 + example: YWxsCgpOb25lLDM1ODcwOA + schema: + type: string - in: query name: membership - type: string - enum: - - join - - invite - - knock - - leave - - ban description: |- The kind of membership to filter for. Defaults to no filtering if unspecified. When specified alongside `not_membership`, the two parameters create an 'or' condition: either the membership *is* the same as `membership` **or** *is not* the same as `not_membership`. - x-example: "join" + example: join + schema: + type: string + enum: + - join + - invite + - knock + - leave + - ban - in: query name: not_membership - type: string - enum: - - join - - invite - - knock - - leave - - ban description: |- The kind of membership to exclude from the results. Defaults to no filtering if unspecified. - x-example: leave + example: leave + schema: + type: string + enum: + - join + - invite + - knock + - leave + - ban security: - accessToken: [] responses: - 200: + "200": description: |- A list of members of the room. If you are joined to the room then this will be the current members of the room. If you have left the room then this will be the members of the room when you left. - examples: - application/json: { - "chunk": [ - { - "room_id": "!636q39766251:example.com", - "$ref": "../../event-schemas/examples/m.room.member.yaml" + content: + application/json: + schema: + type: object + properties: + chunk: + type: array + items: + $ref: definitions/client_event.yaml + examples: + response: + value: { + "chunk": [ + { + "room_id": "!636q39766251:example.com", + "$ref": "../../event-schemas/examples/m.room.member.yaml" + } + ] } - ] - } - schema: - type: object - properties: - chunk: - type: array - items: - $ref: "definitions/client_event.yaml" - 403: - description: > - You aren't a member of the room and weren't previously a - member of the room. + "403": + description: | + You aren't a member of the room and weren't previously a member of the room. tags: - Room participation "/rooms/{roomId}/joined_members": get: summary: Gets the list of currently joined users and their profile data. - description: - This API returns a map of MXIDs to member info objects for members of the room. The current user must be in the room for it to work, unless it is an Application Service in which case any of the AS's users must be in the room. - This API is primarily for Application Services and should be faster to respond than `/members` as it can be implemented more efficiently on the server. + description: This API returns a map of MXIDs to member info objects for members + of the room. The current user must be in the room for it to work, unless + it is an Application Service in which case any of the AS's users must be + in the room. This API is primarily for Application Services and should + be faster to respond than `/members` as it can be implemented more + efficiently on the server. operationId: getJoinedMembersByRoom parameters: - in: path - type: string name: roomId description: The room to get the members of. required: true - x-example: "!636q39766251:example.com" + example: "!636q39766251:example.com" + schema: + type: string security: - accessToken: [] responses: - 200: - description: |- - A map of MXID to room member objects. - examples: - application/json: { - "joined": { - "@bar:example.com": { - "display_name": "Bar", - "avatar_url": "mxc://riot.ovh/printErCATzZijQsSDWorRaK" - } - } - } - schema: - type: object - properties: - joined: - additionalProperties: - title: RoomMember - type: object - properties: - display_name: - type: string - description: The display name of the user this object is representing. - avatar_url: - type: string - format: uri - description: The avatar of the user this object is representing, as an [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris). - description: A map from user ID to a RoomMember object. + "200": + description: A map of MXID to room member objects. + content: + application/json: + schema: type: object - 403: - description: > + properties: + joined: + additionalProperties: + title: RoomMember + type: object + properties: + display_name: + type: string + description: The display name of the user this object is representing. + avatar_url: + type: string + format: uri + description: The avatar of the user this object is representing, as an [`mxc://` + URI](/client-server-api/#matrix-content-mxc-uris). + description: A map from user ID to a RoomMember object. + type: object + examples: + response: + value: { + "joined": { + "@bar:example.com": { + "display_name": "Bar", + "avatar_url": "mxc://riot.ovh/printErCATzZijQsSDWorRaK" + } + } + } + "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 diff --git a/data/api/client-server/search.yaml b/data/api/client-server/search.yaml index 2d45fe2a4..981f93aa8 100644 --- a/data/api/client-server/search.yaml +++ b/data/api/client-server/search.yaml @@ -11,44 +11,33 @@ # 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 Search 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 Search API + version: 1.0.0 paths: - "/search": + /search: post: summary: Perform a server-side search. - description: |- - Performs a full text search across different categories. + description: Performs a full text search across different categories. operationId: search security: - accessToken: [] parameters: - in: query name: next_batch - type: string description: |- The point to return events from. If given, this should be a `next_batch` result from a previous call to this endpoint. - x-example: "YWxsCgpOb25lLDM1ODcwOA" - - in: body - name: body - required: true + example: YWxsCgpOb25lLDM1ODcwOA schema: - type: object - example: { + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { "search_categories": { "room_events": { "keys": [ @@ -66,300 +55,323 @@ paths: } } } - properties: - search_categories: - type: object - title: "Categories" - description: Describes which categories to search in and - their criteria. - properties: - room_events: - type: object - title: Room Events Criteria - description: Mapping of category name to search criteria. - properties: - search_term: - type: string - description: The string to search events for - keys: - type: array - items: + properties: + search_categories: + type: object + title: Categories + description: Describes which categories to search in and their criteria. + properties: + room_events: + type: object + title: Room Events Criteria + description: Mapping of category name to search criteria. + properties: + search_term: type: string - enum: ["content.body", "content.name", "content.topic"] - description: The keys to search. Defaults to all. - filter: - type: object - title: Filter - description: |- - This takes a [filter](/client-server-api/#filtering). - allOf: - - $ref: "definitions/room_event_filter.yaml" - order_by: - title: "Ordering" - type: string - enum: ["recent", "rank"] - description: |- - The order in which to search for results. - By default, this is `"rank"`. - event_context: - title: Include Event Context - type: object - description: |- - Configures whether any context for the events - returned are included in the response. - properties: + description: The string to search events for + keys: + type: array + items: + type: string + enum: + - content.body + - content.name + - content.topic + description: The keys to search. Defaults to all. + filter: + type: object + title: Filter + description: This takes a [filter](/client-server-api/#filtering). + allOf: + - $ref: definitions/room_event_filter.yaml + order_by: + title: Ordering + type: string + enum: + - recent + - rank + description: |- + The order in which to search for results. + By default, this is `"rank"`. + event_context: + title: Include Event Context + type: object + description: |- + Configures whether any context for the events + returned are included in the response. + properties: before_limit: - type: integer - title: "Before limit" - description: |- - How many events before the result are - returned. By default, this is `5`. + type: integer + title: Before limit + description: |- + How many events before the result are + returned. By default, this is `5`. after_limit: - type: integer - title: "After limit" - description: |- - How many events after the result are - returned. By default, this is `5`. + type: integer + title: After limit + description: |- + How many events after the result are + returned. By default, this is `5`. include_profile: - type: boolean - title: "Return profile information" - description: |- - Requests that the server returns the - historic profile information for the users - that sent the events that were returned. - By default, this is `false`. - include_state: - type: boolean - title: Include current state - description: |- - Requests the server return the current state for - each room returned. - groupings: - type: object - title: Groupings - description: |- - Requests that the server partitions the result set - based on the provided list of keys. - properties: - group_by: - type: array - title: Groups - description: List of groups to request. - items: - type: object - title: Group - description: Configuration for group. - properties: - key: - type: string - title: Group Key - description: |- - Key that defines the group. - enum: ["room_id", "sender"] - required: ["search_term"] - required: ["search_categories"] + type: boolean + title: Return profile information + description: |- + Requests that the server returns the + historic profile information for the users + that sent the events that were returned. + By default, this is `false`. + include_state: + type: boolean + title: Include current state + description: |- + Requests the server return the current state for + each room returned. + groupings: + type: object + title: Groupings + description: |- + Requests that the server partitions the result set + based on the provided list of keys. + properties: + group_by: + type: array + title: Groups + description: List of groups to request. + items: + type: object + title: Group + description: Configuration for group. + properties: + key: + type: string + title: Group Key + description: Key that defines the group. + enum: + - room_id + - sender + required: + - search_term + required: + - search_categories + required: true responses: - 200: + "200": description: Results of the search. - schema: - type: object - title: Results - required: ["search_categories"] - properties: - search_categories: + content: + application/json: + schema: type: object - title: Result Categories - description: Describes which categories to search in and - their criteria. + title: Results + required: + - search_categories properties: - room_events: + search_categories: type: object - title: Result Room Events - description: Mapping of category name to search criteria. + title: Result Categories + description: Describes which categories to search in and their criteria. properties: - count: - type: integer - description: An approximate count of the total number of results found. - highlights: - type: array - title: Highlights - description: List of words which should be highlighted, useful for stemming which may change the query terms. - items: - type: string - results: - type: array - title: Results - description: List of results in the requested order. - items: - type: object - title: Result - description: The result object. - properties: - rank: - type: number - description: A number that describes how closely - this result matches the search. Higher is - closer. - result: - type: object - title: Event - description: The event that matched. - allOf: - - "$ref": "definitions/client_event.yaml" - context: + room_events: + type: object + title: Result Room Events + description: Mapping of category name to search criteria. + properties: + count: + type: integer + description: An approximate count of the total number of results found. + highlights: + type: array + title: Highlights + description: List of words which should be highlighted, useful for stemming + which may change the query terms. + items: + type: string + results: + type: array + title: Results + description: List of results in the requested order. + items: type: object - title: Event Context - description: Context for result, if requested. + title: Result + description: The result object. properties: - start: - type: string - title: Start Token - description: |- - Pagination token for the start of the chunk - end: - type: string - title: End Token - description: |- - Pagination token for the end of the chunk - profile_info: + rank: + type: number + description: A number that describes how closely this result matches the search. + Higher is closer. + result: type: object - title: Profile Information - description: |- - The historic profile information of the - users that sent the events returned. - - The `string` key is the user ID for which - the profile belongs to. - additionalProperties: - type: object - title: User Profile - properties: - displayname: - type: string - title: Display name - avatar_url: - type: string - format: uri - title: Avatar Url - events_before: - type: array - title: Events Before - description: Events just before the result. - items: - title: Event - type: object - "$ref": "definitions/client_event.yaml" - events_after: - type: array - title: Events After - description: Events just after the result. - items: - title: Event - type: object - "$ref": "definitions/client_event.yaml" - state: - type: object - title: Current state - description: |- - The current state for every room in the results. - This is included if the request had the - `include_state` key set with a value of `true`. + title: Event + description: The event that matched. + allOf: + - $ref: definitions/client_event.yaml + context: + type: object + title: Event Context + description: Context for result, if requested. + properties: + start: + type: string + title: Start Token + description: Pagination token for the start of the chunk + end: + type: string + title: End Token + description: Pagination token for the end of the chunk + profile_info: + type: object + title: Profile Information + description: |- + The historic profile information of the + users that sent the events returned. - The `string` key is the room ID for which the `State - Event` array belongs to. - additionalProperties: - type: array - title: Room State - items: - "$ref": "definitions/client_event.yaml" - groups: - type: object - title: Groups - description: |- - Any groups that were requested. + The `string` key is the user ID for which + the profile belongs to. + additionalProperties: + type: object + title: User Profile + properties: + displayname: + type: string + title: Display name + avatar_url: + type: string + format: uri + title: Avatar Url + events_before: + type: array + title: Events Before + description: Events just before the result. + items: + title: Event + type: object + $ref: definitions/client_event.yaml + events_after: + type: array + title: Events After + description: Events just after the result. + items: + title: Event + type: object + $ref: definitions/client_event.yaml + state: + type: object + title: Current state + description: |- + The current state for every room in the results. + This is included if the request had the + `include_state` key set with a value of `true`. - The outer `string` key is the group key requested (eg: `room_id` - or `sender`). The inner `string` key is the grouped value (eg: - a room's ID or a user's ID). - additionalProperties: - type: object - title: Group Key - description: The results for a given group. - additionalProperties: + The `string` key is the room ID for which the `State + Event` array belongs to. + additionalProperties: + type: array + title: Room State + items: + $ref: definitions/client_event.yaml + groups: type: object - title: Group Value + title: Groups + description: |- + Any groups that were requested. + + The outer `string` key is the group key requested (eg: `room_id` + or `sender`). The inner `string` key is the grouped value (eg: + a room's ID or a user's ID). + additionalProperties: + type: object + title: Group Key + description: The results for a given group. + additionalProperties: + type: object + title: Group Value + description: The results for a particular group value. + properties: + next_batch: + type: string + title: Next Batch in Group + description: |- + Token that can be used to get the next batch + of results in the group, by passing as the + `next_batch` parameter to the next call. If + this field is absent, there are no more + results in this group. + order: + type: integer + title: Group Order + description: |- + Key that can be used to order different + groups. + results: + type: array + description: Which results are in this group. + items: + type: string + title: Result Event ID + next_batch: + type: string + title: Next Batch description: |- - The results for a particular group value. - properties: - next_batch: - type: string - title: Next Batch in Group - description: |- - Token that can be used to get the next batch - of results in the group, by passing as the - `next_batch` parameter to the next call. If - this field is absent, there are no more - results in this group. - order: - type: integer - title: Group Order - description: |- - Key that can be used to order different - groups. - results: - type: array - description: |- - Which results are in this group. - items: - type: string - title: Result Event ID - next_batch: - type: string - title: Next Batch - description: |- - Token that can be used to get the next batch of - results, by passing as the `next_batch` parameter to - the next call. If this field is absent, there are no - more results. - examples: - application/json: { - "search_categories": { - "room_events": { - "groups": { - "room_id": { - "!qPewotXpIctQySfjSy:localhost": { - "order": 1, - "next_batch": "BdgFsdfHSf-dsFD", - "results": [ - "$144429830826TWwbB:localhost" - ] + Token that can be used to get the next batch of + results, by passing as the `next_batch` parameter to + the next call. If this field is absent, there are no + more results. + examples: + response: + value: { + "search_categories": { + "room_events": { + "groups": { + "room_id": { + "!qPewotXpIctQySfjSy:localhost": { + "order": 1, + "next_batch": "BdgFsdfHSf-dsFD", + "results": [ + "$144429830826TWwbB:localhost" + ] + } } - } - }, - "highlights": [ - "martians", - "men" - ], - "next_batch": "5FdgFsd234dfgsdfFD", - "count": 1224, - "results": [ - { - "rank": 0.00424866, - "result": { - "room_id": "!qPewotXpIctQySfjSy:localhost", - "event_id": "$144429830826TWwbB:localhost", - "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + }, + "highlights": [ + "martians", + "men" + ], + "next_batch": "5FdgFsd234dfgsdfFD", + "count": 1224, + "results": [ + { + "rank": 0.00424866, + "result": { + "room_id": "!qPewotXpIctQySfjSy:localhost", + "event_id": "$144429830826TWwbB:localhost", + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + } } - } - ] + ] + } } } - } - 400: + "400": description: Part of the request was invalid. - 429: + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Search +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 diff --git a/data/api/client-server/space_hierarchy.yaml b/data/api/client-server/space_hierarchy.yaml index 9469d0c1b..f7b985113 100644 --- a/data/api/client-server/space_hierarchy.yaml +++ b/data/api/client-server/space_hierarchy.yaml @@ -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 Space Hierarchy API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Space Hierarchy API + version: 1.0.0 paths: "/rooms/{roomId}/hierarchy": get: @@ -44,30 +33,32 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room ID of the space to get a hierarchy for. required: true - x-example: "!space:example.org" + example: "!space:example.org" + schema: + type: string - in: query - type: boolean name: suggested_only description: |- Optional (default `false`) flag to indicate whether or not the server should only consider suggested rooms. Suggested rooms are annotated in their [`m.space.child`](#mspacechild) event contents. - x-example: true + example: true + schema: + type: boolean - in: query - type: integer name: limit description: |- Optional limit for the maximum number of rooms to include per response. Must be an integer greater than zero. Servers should apply a default value, and impose a maximum value to avoid resource exhaustion. - x-example: 20 + example: 20 + schema: + type: integer - in: query - type: integer name: max_depth description: |- Optional limit for how far to go into the space. Must be a non-negative integer. @@ -75,91 +66,117 @@ paths: When reached, no further child rooms will be returned. Servers should apply a default value, and impose a maximum value to avoid resource exhaustion. - x-example: 5 + example: 5 + schema: + type: integer - in: query - type: string name: from description: |- A pagination token from a previous result. If specified, `max_depth` and `suggested_only` cannot be changed from the first request. - x-example: "next_batch_token" + example: next_batch_token + schema: + type: string responses: - 200: + "200": + description: A portion of the space tree, starting at the provided room ID. + content: + application/json: + schema: + type: object + properties: + rooms: + type: array + description: The rooms for the current page, with the current filters. + items: + allOf: + - $ref: definitions/public_rooms_chunk.yaml + - type: object + title: ChildRoomsChunk + properties: + room_type: + type: string + description: The `type` of room (from + [`m.room.create`](/client-server-api/#mroomcreate)), + if any. + children_state: + type: array + description: |- + The [`m.space.child`](#mspacechild) events of the space-room, represented + as [Stripped State Events](#stripped-state) with an added `origin_server_ts` key. + + If the room is not a space-room, this should be empty. + items: + allOf: + - $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml + - type: object + title: StrippedChildStateEvent + properties: + origin_server_ts: + type: integer + format: int64 + description: The `origin_server_ts` for the event. + required: + - origin_server_ts + required: + - children_state + next_batch: + type: string + description: |- + A token to supply to `from` to keep paginating the responses. Not present when there are + no further results. + required: + - rooms + examples: + response: + value: { + "rooms": [ + { + "room_id": "!space:example.org", + "avatar_url": "mxc://example.org/abcdef", + "guest_can_join": false, + "name": "The First Space", + "topic": "No other spaces were created first, ever", + "world_readable": true, + "join_rule": "public", + "room_type": "m.space", + "num_joined_members": 42, + "canonical_alias": "#general:example.org", + "children_state": [ + { + "type": "m.space.child", + "state_key": "!a:example.org", + "content": { + "via": [ + "example.org" + ] + }, + "sender": "@alice:example.org", + "origin_server_ts": 1629413349153 + } + ] + } + ], + "next_batch": "next_batch_token" + } + "400": description: |- - A portion of the space tree, starting at the provided room ID. - examples: - application/json: { - "rooms": [ - { - "room_id": "!space:example.org", - "avatar_url": "mxc://example.org/abcdef", - "guest_can_join": false, - "name": "The First Space", - "topic": "No other spaces were created first, ever", - "world_readable": true, - "join_rule": "public", - "room_type": "m.space", - "num_joined_members": 42, - "canonical_alias": "#general:example.org", - "children_state": [ - { - "type": "m.space.child", - "state_key": "!a:example.org", - "content": { - "via": ["example.org"] - }, - "sender": "@alice:example.org", - "origin_server_ts": 1629413349153 - } - ] - } - ], - "next_batch": "next_batch_token" - } - schema: - type: object - properties: - rooms: - type: array - description: |- - The rooms for the current page, with the current filters. - items: - allOf: - - $ref: "definitions/public_rooms_chunk.yaml" - - type: object - title: ChildRoomsChunk - properties: - # Override x-addedInMatrixVersion for room_type (this endpoint had it first) - room_type: - type: string - description: |- - The `type` of room (from [`m.room.create`](/client-server-api/#mroomcreate)), if any. - children_state: - type: array - description: |- - The [`m.space.child`](#mspacechild) events of the space-room, represented - as [Stripped State Events](#stripped-state) with an added `origin_server_ts` key. + The request was invalid in some way. A meaningful `errcode` + and description error text will be returned. Example reasons for rejection are: - If the room is not a space-room, this should be empty. - items: - allOf: - - $ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml" - - type: object - title: StrippedChildStateEvent - properties: - origin_server_ts: - type: integer - format: int64 - description: The `origin_server_ts` for the event. - required: [origin_server_ts] - required: [children_state] - next_batch: - type: string - description: |- - A token to supply to `from` to keep paginating the responses. Not present when there are - no further results. - required: [rooms] - 403: + - The `from` token is unknown to the server. + - `suggested_only` or `max_depth` changed during pagination. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_INVALID_PARAM", + "error": "suggested_only and max_depth cannot change on paginated requests" + } + "403": description: |- The user cannot view or peek on the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejection are: @@ -167,30 +184,36 @@ paths: - The room is not set up for peeking. - The user has been banned from the room. - The room does not exist. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "You are not allowed to view this room." - } - schema: - "$ref": "definitions/errors/error.yaml" - 400: - description: |- - The request was invalid in some way. A meaningful `errcode` - and description error text will be returned. Example reasons for rejection are: - - - The `from` token is unknown to the server. - - `suggested_only` or `max_depth` changed during pagination. - examples: - application/json: { - "errcode": "M_INVALID_PARAM", - "error": "suggested_only and max_depth cannot change on paginated requests" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You are not allowed to view this room." + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Spaces +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/sso_login_redirect.yaml b/data/api/client-server/sso_login_redirect.yaml index 07278aafa..9f9d758bc 100644 --- a/data/api/client-server/sso_login_redirect.yaml +++ b/data/api/client-server/sso_login_redirect.yaml @@ -11,17 +11,12 @@ # 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 SSO Login API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 + title: Matrix Client-Server SSO Login API + version: 1.0.0 paths: - "/login/sso/redirect": + /login/sso/redirect: get: x-addedInMatrixVersion: "1.1" summary: Redirect the user's browser to the SSO interface. @@ -35,20 +30,22 @@ paths: operationId: redirectToSSO parameters: - in: query - type: string name: redirectUrl description: |- URI to which the user will be redirected after the homeserver has authenticated the user with SSO. required: true + schema: + type: string responses: - 302: + "302": description: A redirect to the SSO interface. headers: Location: - type: "string" + schema: + type: string tags: - - Session management + - Session management "/login/sso/redirect/{idpId}": get: x-addedInMatrixVersion: "1.1" @@ -63,29 +60,44 @@ paths: operationId: redirectToIdP parameters: - in: path - type: string name: idpId required: true description: |- The `id` of the IdP from the `m.login.sso` `identity_providers` array denoting the user's selection. + schema: + type: string - in: query - type: string name: redirectUrl description: |- URI to which the user will be redirected after the homeserver has authenticated the user with SSO. required: true + schema: + type: string responses: - 302: + "302": description: A redirect to the SSO interface. headers: Location: - type: "string" - 404: + schema: + type: string + "404": description: |- The IdP ID was not recognized by the server. The server is encouraged to provide a user-friendly page explaining the error given the user will be navigated to it. tags: - - Session management + - Session management +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v3 diff --git a/data/api/client-server/sync.yaml b/data/api/client-server/sync.yaml index 487a70191..0b22a96e4 100644 --- a/data/api/client-server/sync.yaml +++ b/data/api/client-server/sync.yaml @@ -11,22 +11,12 @@ # 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 sync API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https -basePath: /_matrix/client/v3 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server sync API + version: 1.0.0 paths: - "/sync": + /sync: get: summary: Synchronise the client's state and receive new messages. description: |- @@ -57,7 +47,6 @@ paths: parameters: - in: query name: filter - type: string description: |- The ID of a filter created using the filter API or a filter JSON object encoded as a string. The server will detect whether it is @@ -68,17 +57,19 @@ paths: long poll requests. See [Filtering](/client-server-api/#filtering) for more information. - x-example: "66696p746572" + example: 66696p746572 + schema: + type: string - in: query name: since - type: string description: |- A point in time to continue a sync from. This should be the `next_batch` token returned by an earlier call to this endpoint. - x-example: "s72594_4483_1934" + example: s72594_4483_1934 + schema: + type: string - in: query name: full_state - type: boolean description: |- Controls whether to include the full state for all rooms the user is a member of. @@ -93,11 +84,11 @@ paths: changed since the point indicated by `since` will be returned. By default, this is `false`. - x-example: "false" + example: "false" + schema: + type: boolean - in: query name: set_presence - type: string - enum: ["offline", "online", "unavailable"] description: |- Controls whether the client is automatically marked as online by polling this API. If this parameter is omitted then the client is @@ -105,10 +96,15 @@ paths: the parameter is set to "offline" then the client is not marked as being online when it uses this API. When set to "unavailable", the client is marked as being idle. - x-example: "offline" + example: offline + schema: + type: string + enum: + - offline + - online + - unavailable - in: query name: timeout - type: integer description: |- The maximum time to wait, in milliseconds, before returning this request. If no events (or other data) become available before this @@ -116,405 +112,436 @@ paths: By default, this is `0`, so the server will return immediately even if the response is empty. - x-example: 30000 + example: 30000 + schema: + type: integer responses: - 200: - description: - The initial snapshot or delta for the client to use to update their + "200": + description: The initial snapshot or delta for the client to use to update their state. - schema: - type: object - properties: - next_batch: - type: string - description: |- - The batch token to supply in the `since` param of the next - `/sync` request. - rooms: - title: Rooms + content: + application/json: + schema: type: object - description: |- - Updates to rooms. properties: - join: - title: Joined Rooms - type: object + next_batch: + type: string description: |- - The rooms that the user has joined, mapped as room ID to - room information. - additionalProperties: - title: Joined Room - type: object - properties: - summary: - title: RoomSummary + The batch token to supply in the `since` param of the next + `/sync` request. + rooms: + title: Rooms + type: object + description: Updates to rooms. + properties: + join: + title: Joined Rooms + type: object + description: |- + The rooms that the user has joined, mapped as room ID to + room information. + additionalProperties: + title: Joined Room type: object - description: |- - Information about the room which clients may need to - correctly render it to users. properties: - "m.heroes": - type: array + summary: + title: RoomSummary + type: object description: |- - The users which can be used to generate a room name - if the room does not have one. Required if the room's - `m.room.name` or `m.room.canonical_alias` state events - are unset or empty. + Information about the room which clients may need to + correctly render it to users. + properties: + m.heroes: + type: array + description: |- + The users which can be used to generate a room name + if the room does not have one. Required if the room's + `m.room.name` or `m.room.canonical_alias` state events + are unset or empty. - This should be the first 5 members of the room, ordered - by stream ordering, which are joined or invited. The - list must never include the client's own user ID. When - no joined or invited members are available, this should - consist of the banned and left users. More than 5 members - may be provided, however less than 5 should only be provided - when there are less than 5 members to represent. + This should be the first 5 members of the room, ordered + by stream ordering, which are joined or invited. The + list must never include the client's own user ID. When + no joined or invited members are available, this should + consist of the banned and left users. More than 5 members + may be provided, however less than 5 should only be provided + when there are less than 5 members to represent. - When lazy-loading room members is enabled, the membership - events for the heroes MUST be included in the `state`, - unless they are redundant. When the list of users changes, - the server notifies the client by sending a fresh list of - heroes. If there are no changes since the last sync, this - field may be omitted. - items: - type: string - "m.joined_member_count": - type: integer + When lazy-loading room members is enabled, the membership + events for the heroes MUST be included in the `state`, + unless they are redundant. When the list of users changes, + the server notifies the client by sending a fresh list of + heroes. If there are no changes since the last sync, this + field may be omitted. + items: + type: string + m.joined_member_count: + type: integer + description: |- + The number of users with `membership` of `join`, + including the client's own user ID. If this field has + not changed since the last sync, it may be omitted. + Required otherwise. + m.invited_member_count: + type: integer + description: |- + The number of users with `membership` of `invite`. + If this field has not changed since the last sync, it + may be omitted. Required otherwise. + state: + title: State + type: object description: |- - The number of users with `membership` of `join`, - including the client's own user ID. If this field has - not changed since the last sync, it may be omitted. - Required otherwise. - "m.invited_member_count": - type: integer + Updates to the state, between the time indicated by + the `since` parameter, and the start of the + `timeline` (or all state up to the start of the + `timeline`, if `since` is not given, or + `full_state` is true). + + N.B. state updates for `m.room.member` events will + be incomplete if `lazy_load_members` is enabled in + the `/sync` filter, and only return the member events + required to display the senders of the timeline events + in this response. + allOf: + - $ref: definitions/state_event_batch.yaml + timeline: + title: Timeline + type: object description: |- - The number of users with `membership` of `invite`. - If this field has not changed since the last sync, it - may be omitted. Required otherwise. - state: - title: State - type: object - description: |- - Updates to the state, between the time indicated by - the `since` parameter, and the start of the - `timeline` (or all state up to the start of the - `timeline`, if `since` is not given, or - `full_state` is true). + The timeline of messages and state changes in the + room. + allOf: + - $ref: definitions/timeline_batch.yaml + ephemeral: + title: Ephemeral + type: object + description: |- + The new ephemeral events in the room (events that + aren't recorded in the timeline or state of the + room). In this version of the spec, these are + [typing notification](#typing-notifications) and + [read receipt](#receipts) events. + allOf: + - $ref: definitions/event_batch.yaml + account_data: + title: Account Data + type: object + description: |- + The private data that this user has attached to + this room. + allOf: + - $ref: definitions/event_batch.yaml + unread_notifications: + title: Unread Notification Counts + type: object + description: |- + Counts of unread notifications for this room. See the + [Receiving notifications](/client-server-api/#receiving-notifications) section + for more information on how these are calculated. - N.B. state updates for `m.room.member` events will - be incomplete if `lazy_load_members` is enabled in - the `/sync` filter, and only return the member events - required to display the senders of the timeline events - in this response. - allOf: - - $ref: "definitions/state_event_batch.yaml" - timeline: - title: Timeline - type: object - description: |- - The timeline of messages and state changes in the - room. - allOf: - - $ref: "definitions/timeline_batch.yaml" - ephemeral: - title: Ephemeral - type: object - description: |- - The new ephemeral events in the room (events that - aren't recorded in the timeline or state of the - room). In this version of the spec, these are - [typing notification](#typing-notifications) and - [read receipt](#receipts) events. - allOf: - - $ref: "definitions/event_batch.yaml" - account_data: - title: Account Data - type: object - description: |- - The private data that this user has attached to - this room. - allOf: - - $ref: "definitions/event_batch.yaml" - unread_notifications: - title: Unread Notification Counts - type: object - description: |- - Counts of unread notifications for this room. See the - [Receiving notifications](/client-server-api/#receiving-notifications) section - for more information on how these are calculated. + If `unread_thread_notifications` was specified as `true` on the `RoomEventFilter`, + these counts will only be for the main timeline rather than all events in the room. + See the [threading module](#threading) for more information. + x-changedInMatrixVersion: + "1.4": | + Updated to reflect behaviour of having `unread_thread_notifications` as `true` in + the `RoomEventFilter` for `/sync`. + properties: + highlight_count: + title: Highlighted notification count + type: integer + description: The number of unread notifications for this room with the highlight + flag set. + notification_count: + title: Total notification count + type: integer + description: The total number of unread notifications for this room. + unread_thread_notifications: + title: Unread Thread Notification Counts + type: object + description: |- + If `unread_thread_notifications` was specified as `true` on the `RoomEventFilter`, + the notification counts for each [thread](#threading) in this room. The object is + keyed by thread root ID, with values matching `unread_notifications`. - If `unread_thread_notifications` was specified as `true` on the `RoomEventFilter`, - these counts will only be for the main timeline rather than all events in the room. - See the [threading module](#threading) for more information. - x-changedInMatrixVersion: - 1.4: | - Updated to reflect behaviour of having `unread_thread_notifications` as `true` in - the `RoomEventFilter` for `/sync`. + If a thread does not have any notifications it can be omitted from this object. If + no threads have notification counts, this whole object can be omitted. + x-addedInMatrixVersion: "1.4" + additionalProperties: + title: ThreadNotificationCounts + type: object + properties: + highlight_count: + title: ThreadedHighlightNotificationCount + type: integer + description: The number of unread notifications for this *thread* with the + highlight flag set. + notification_count: + title: ThreadedTotalNotificationCount + type: integer + description: The total number of unread notifications for this *thread*. + invite: + title: Invited Rooms + type: object + description: |- + The rooms that the user has been invited to, mapped as room ID to + room information. + additionalProperties: + title: Invited Room + type: object properties: - highlight_count: - title: Highlighted notification count - type: integer - description: The number of unread notifications - for this room with the highlight flag set. - notification_count: - title: Total notification count - type: integer - description: The total number of unread notifications - for this room. - unread_thread_notifications: - title: Unread Thread Notification Counts + invite_state: + title: InviteState + type: object + description: |- + The [stripped state](#stripped-state) of a room that the user has been invited + to. + properties: + events: + description: The [stripped state events](#stripped-state) that form the invite + state. + items: + $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml + type: array + knock: + title: Knocked rooms + type: object + description: The rooms that the user has knocked upon, mapped as room ID to room + information. + additionalProperties: + title: Knocked Room type: object - description: |- - If `unread_thread_notifications` was specified as `true` on the `RoomEventFilter`, - the notification counts for each [thread](#threading) in this room. The object is - keyed by thread root ID, with values matching `unread_notifications`. - - If a thread does not have any notifications it can be omitted from this object. If - no threads have notification counts, this whole object can be omitted. - x-addedInMatrixVersion: "1.4" - additionalProperties: - title: ThreadNotificationCounts - type: object - properties: - highlight_count: - title: ThreadedHighlightNotificationCount - type: integer - description: |- - The number of unread notifications for this *thread* with the highlight flag set. - notification_count: - title: ThreadedTotalNotificationCount - type: integer - description: |- - The total number of unread notifications for this *thread*. - invite: - title: Invited Rooms - type: object - description: |- - The rooms that the user has been invited to, mapped as room ID to - room information. - additionalProperties: - title: Invited Room - type: object - properties: - invite_state: - title: InviteState + properties: + knock_state: + title: KnockState + type: object + description: The [stripped state](#stripped-state) of a room that the user has + knocked upon. + properties: + events: + description: The [stripped state events](#stripped-state) that form the knock + state. + items: + $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml + type: array + leave: + title: Left rooms + type: object + description: |- + The rooms that the user has left or been banned from, mapped as room ID to + room information. + additionalProperties: + title: Left Room type: object - description: |- - The [stripped state](#stripped-state) of a room that the user has been invited - to. properties: - events: - description: The [stripped state events](#stripped-state) that form the invite state. - items: - $ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml" - type: array - knock: - title: Knocked rooms + state: + title: State + type: object + description: The state updates for the room up to the start of the timeline. + allOf: + - $ref: definitions/state_event_batch.yaml + timeline: + title: Timeline + type: object + description: |- + The timeline of messages and state changes in the + room up to the point when the user left. + allOf: + - $ref: definitions/timeline_batch.yaml + account_data: + title: Account Data + type: object + description: |- + The private data that this user has attached to + this room. + allOf: + - $ref: definitions/event_batch.yaml + presence: + title: Presence + type: object + description: The updates to the presence status of other users. + allOf: + - $ref: definitions/event_batch.yaml + account_data: + title: Account Data + type: object + description: The global private data created by this user. + allOf: + - $ref: definitions/event_batch.yaml + to_device: + title: ToDevice type: object description: |- - The rooms that the user has knocked upon, mapped as room ID to room information. - additionalProperties: - title: Knocked Room - type: object - properties: - knock_state: - title: KnockState - type: object - description: |- - The [stripped state](#stripped-state) of a room that the user has knocked upon. - properties: - events: - description: The [stripped state events](#stripped-state) that form the knock state. - items: - $ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml" - type: array - leave: - title: Left rooms + Information on the send-to-device messages for the client + device, as defined in [Send-to-Device messaging](/client-server-api/#extensions-to-sync). + device_lists: + title: DeviceLists type: object description: |- - The rooms that the user has left or been banned from, mapped as room ID to - room information. + Information on end-to-end device updates, as specified in + [End-to-end encryption](/client-server-api/#e2e-extensions-to-sync). + device_one_time_keys_count: + title: One-time keys count + type: object additionalProperties: - title: Left Room - type: object - properties: - state: - title: State - type: object - description: |- - The state updates for the room up to the start of the timeline. - allOf: - - $ref: "definitions/state_event_batch.yaml" - timeline: - title: Timeline - type: object - description: |- - The timeline of messages and state changes in the - room up to the point when the user left. - allOf: - - $ref: "definitions/timeline_batch.yaml" - account_data: - title: Account Data - type: object - description: |- - The private data that this user has attached to - this room. - allOf: - - $ref: "definitions/event_batch.yaml" - presence: - title: Presence - type: object - description: |- - The updates to the presence status of other users. - allOf: - - $ref: "definitions/event_batch.yaml" - account_data: - title: Account Data - type: object - description: |- - The global private data created by this user. - allOf: - - $ref: "definitions/event_batch.yaml" - to_device: - title: ToDevice - type: object - description: |- - Information on the send-to-device messages for the client - device, as defined in [Send-to-Device messaging](/client-server-api/#extensions-to-sync). - device_lists: - title: DeviceLists - type: object - description: |- - Information on end-to-end device updates, as specified in - [End-to-end encryption](/client-server-api/#e2e-extensions-to-sync). - device_one_time_keys_count: - title: One-time keys count - type: object - additionalProperties: - type: integer - description: |- - Information on end-to-end encryption keys, as specified - in [End-to-end encryption](/client-server-api/#e2e-extensions-to-sync). - required: - - next_batch - examples: - application/json: { - "next_batch": "s72595_4483_1934", - "presence": { - "events": [ - {"$ref": "../../event-schemas/examples/m.presence.yaml"} - ] - }, - "account_data": { - "events": [ - { - "type": "org.example.custom.config", - "content": { - "custom_config_key": "custom_config_value" - } - } - ] - }, - "rooms": { - "join": { - "!726s6s6q:example.com": { - "summary": { - "m.heroes": [ - "@alice:example.com", - "@bob:example.com" - ], - "m.joined_member_count": 2, - "m.invited_member_count": 0 - }, - "state": { - "events": [ - { - "$ref": "../../event-schemas/examples/m.room.member.yaml" + type: integer + description: |- + Information on end-to-end encryption keys, as specified + in [End-to-end encryption](/client-server-api/#e2e-extensions-to-sync). + required: + - next_batch + examples: + response: + value: { + "next_batch": "s72595_4483_1934", + "presence": { + "events": [ + { + "$ref": "../../event-schemas/examples/m.presence.yaml" + } + ] + }, + "account_data": { + "events": [ + { + "type": "org.example.custom.config", + "content": { + "custom_config_key": "custom_config_value" } - ] - }, - "timeline": { - "events": [ - { - "$ref": "../../event-schemas/examples/m.room.member.yaml" + } + ] + }, + "rooms": { + "join": { + "!726s6s6q:example.com": { + "summary": { + "m.heroes": [ + "@alice:example.com", + "@bob:example.com" + ], + "m.joined_member_count": 2, + "m.invited_member_count": 0 }, - { - "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" - } - ], - "limited": true, - "prev_batch": "t34-23535_0_0" - }, - "ephemeral": { - "events": [ - {"$ref": "../../event-schemas/examples/m.typing.yaml"}, - {"$ref": "../../event-schemas/examples/m.receipt.yaml"} - ] - }, - "account_data": { - "events": [ - {"$ref": "../../event-schemas/examples/m.tag.yaml"}, - { - "type": "org.example.custom.room.config", - "content": { - "custom_config_key": "custom_config_value" + "state": { + "events": [ + { + "$ref": "../../event-schemas/examples/m.room.member.yaml" + } + ] + }, + "timeline": { + "events": [ + { + "$ref": "../../event-schemas/examples/m.room.member.yaml" + }, + { + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + } + ], + "limited": true, + "prev_batch": "t34-23535_0_0" + }, + "ephemeral": { + "events": [ + { + "$ref": "../../event-schemas/examples/m.typing.yaml" + }, + { + "$ref": "../../event-schemas/examples/m.receipt.yaml" + } + ] + }, + "account_data": { + "events": [ + { + "$ref": "../../event-schemas/examples/m.tag.yaml" + }, + { + "type": "org.example.custom.room.config", + "content": { + "custom_config_key": "custom_config_value" + } + } + ] + }, + "unread_notifications": { + "highlight_count": 1, + "notification_count": 5 + }, + "unread_thread_notifications": { + "$threadroot": { + "highlight_count": 3, + "notification_count": 6 } } - ] - }, - "unread_notifications": { - "highlight_count": 1, - "notification_count": 5 - }, - "unread_thread_notifications": { - "$threadroot": { - "highlight_count": 3, - "notification_count": 6 } - } - } - }, - "invite": { - "!696r7674:example.com": { - "invite_state": { - "events": [ - { - "sender": "@alice:example.com", - "type": "m.room.name", - "state_key": "", - "content": {"name": "My Room Name"} - }, - { - "sender": "@alice:example.com", - "type": "m.room.member", - "state_key": "@bob:example.com", - "content": {"membership": "invite"} + }, + "invite": { + "!696r7674:example.com": { + "invite_state": { + "events": [ + { + "sender": "@alice:example.com", + "type": "m.room.name", + "state_key": "", + "content": { + "name": "My Room Name" + } + }, + { + "sender": "@alice:example.com", + "type": "m.room.member", + "state_key": "@bob:example.com", + "content": { + "membership": "invite" + } + } + ] } - ] - } - } - }, - "knock": { - "!223asd456:example.com": { - "knock_state": { - "events": [ - { - "sender": "@alice:example.com", - "type": "m.room.name", - "state_key": "", - "content": {"name": "My Room Name"} - }, - { - "sender": "@bob:example.com", - "type": "m.room.member", - "state_key": "@bob:example.com", - "content": {"membership": "knock"} + } + }, + "knock": { + "!223asd456:example.com": { + "knock_state": { + "events": [ + { + "sender": "@alice:example.com", + "type": "m.room.name", + "state_key": "", + "content": { + "name": "My Room Name" + } + }, + { + "sender": "@bob:example.com", + "type": "m.room.member", + "state_key": "@bob:example.com", + "content": { + "membership": "knock" + } + } + ] } - ] - } + } + }, + "leave": {} } - }, - "leave": {} - } - } + } 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 diff --git a/data/api/client-server/tags.yaml b/data/api/client-server/tags.yaml index f04a884a4..f805e02f1 100644 --- a/data/api/client-server/tags.yaml +++ b/data/api/client-server/tags.yaml @@ -12,172 +12,186 @@ # 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 tag 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 tag API + version: 1.0.0 paths: "/user/{userId}/rooms/{roomId}/tags": get: summary: List the tags for a room. - description: |- - List the tags set by a user on a room. + description: List the tags set by a user on a room. operationId: getRoomTags security: - accessToken: [] parameters: - in: path - type: string name: userId required: true description: |- The id of the user to get tags for. The access token must be authorized to make requests for this user ID. - x-example: "@alice:example.com" + example: "@alice:example.com" + schema: + type: string - in: path - type: string name: roomId required: true - description: |- - The ID of the room to get tags for. - x-example: "!726s6s6q:example.com" - responses: - 200: - description: - The list of tags for the user for the room. + description: The ID of the room to get tags for. + example: "!726s6s6q:example.com" schema: - type: object - properties: - tags: + type: string + responses: + "200": + description: The list of tags for the user for the room. + content: + application/json: + schema: type: object - additionalProperties: - title: Tag - type: object - properties: - order: - type: number - format: float - description: |- - A number in a range `[0,1]` describing a relative - position of the room under the given tag. - additionalProperties: true - examples: - application/json: { - "tags": { - "m.favourite": {"order": 0.1}, - "u.Work": {"order": 0.7}, - "u.Customers": {} - } - } + properties: + tags: + type: object + additionalProperties: + title: Tag + type: object + properties: + order: + type: number + format: float + description: |- + A number in a range `[0,1]` describing a relative + position of the room under the given tag. + additionalProperties: true + examples: + response: + value: { + "tags": { + "m.favourite": { + "order": 0.1 + }, + "u.Work": { + "order": 0.7 + }, + "u.Customers": {} + } + } tags: - User data "/user/{userId}/rooms/{roomId}/tags/{tag}": put: summary: Add a tag to a room. - description: |- - Add a tag to the room. + description: Add a tag to the room. operationId: setRoomTag security: - accessToken: [] parameters: - in: path - type: string name: userId required: true description: |- The id of the user to add a tag for. The access token must be authorized to make requests for this user ID. - x-example: "@alice:example.com" + example: "@alice:example.com" + schema: + type: string - in: path - type: string name: roomId required: true - description: |- - The ID of the room to add a tag to. - x-example: "!726s6s6q:example.com" + description: The ID of the room to add a tag to. + example: "!726s6s6q:example.com" + schema: + type: string - in: path - type: string name: tag required: true - description: |- - The tag to add. - x-example: "u.work" - - in: body - name: body - required: true - description: |- - Extra data for the tag, e.g. ordering. + description: The tag to add. + example: u.work schema: - type: object - properties: - order: - type: number - format: float - description: |- - A number in a range `[0,1]` describing a relative - position of the room under the given tag. - additionalProperties: true - example: { - "order": 0.25 - } + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + order: + type: number + format: float + description: |- + A number in a range `[0,1]` describing a relative + position of the room under the given tag. + additionalProperties: true + example: { + "order": 0.25 + } + description: Extra data for the tag, e.g. ordering. + required: true responses: - 200: - description: - The tag was successfully added. - schema: - type: object - examples: - application/json: {} + "200": + description: The tag was successfully added. + content: + application/json: + schema: + type: object + examples: + response: + value: {} tags: - User data delete: summary: Remove a tag from the room. - description: |- - Remove a tag from the room. + description: Remove a tag from the room. operationId: deleteRoomTag security: - accessToken: [] parameters: - in: path - type: string name: userId required: true description: |- The id of the user to remove a tag for. The access token must be authorized to make requests for this user ID. - x-example: "@alice:example.com" + example: "@alice:example.com" + schema: + type: string - in: path - type: string name: roomId required: true - description: |- - The ID of the room to remove a tag from. - x-example: "!726s6s6q:example.com" + description: The ID of the room to remove a tag from. + example: "!726s6s6q:example.com" + schema: + type: string - in: path - type: string name: tag required: true - description: |- - The tag to remove. - x-example: "u.work" - responses: - 200: - description: - The tag was successfully removed. + description: The tag to remove. + example: u.work schema: - type: object - examples: - application/json: {} + type: string + responses: + "200": + description: The tag was successfully removed. + content: + application/json: + schema: + type: object + examples: + response: + value: {} tags: - User data +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 diff --git a/data/api/client-server/third_party_lookup.yaml b/data/api/client-server/third_party_lookup.yaml index ba3684593..de1b0b635 100644 --- a/data/api/client-server/third_party_lookup.yaml +++ b/data/api/client-server/third_party_lookup.yaml @@ -11,23 +11,12 @@ # 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 Third-party Lookup 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 Third-party Lookup API + version: 1.0.0 paths: - "/thirdparty/protocols": + /thirdparty/protocols: get: summary: Retrieve metadata about all protocols that a homeserver supports. description: |- @@ -38,41 +27,48 @@ paths: security: - accessToken: [] responses: - 200: + "200": description: The protocols supported by the homeserver. - schema: - $ref: ../application-service/definitions/protocol_metadata.yaml + content: + application/json: + schema: + $ref: ../application-service/definitions/protocol_metadata.yaml tags: - Third-party Lookup "/thirdparty/protocol/{protocol}": get: summary: Retrieve metadata about a specific protocol that the homeserver supports. - description: |- - Fetches the metadata from the homeserver about a particular third-party protocol. + description: Fetches the metadata from the homeserver about a particular + third-party protocol. operationId: getProtocolMetadata security: - accessToken: [] parameters: - in: path name: protocol - type: string - description: |- - The name of the protocol. + description: The name of the protocol. required: true - x-example: "irc" + example: irc + schema: + type: string responses: - 200: + "200": description: The protocol was found and metadata returned. - schema: - $ref: ../application-service/definitions/protocol.yaml - 404: + content: + application/json: + schema: + $ref: ../application-service/definitions/protocol.yaml + "404": description: The protocol is unknown. - examples: - application/json: { - "errcode": "M_NOT_FOUND" - } - schema: - $ref: definitions/errors/error.yaml + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND" + } tags: - Third-party Lookup "/thirdparty/location/{protocol}": @@ -93,29 +89,36 @@ paths: parameters: - in: path name: protocol - type: string description: The protocol used to communicate to the third-party network. required: true - x-example: irc + example: irc + schema: + type: string - in: query name: searchFields - type: string description: |- One or more custom fields to help identify the third-party location. + schema: + type: string responses: - 200: + "200": description: At least one portal room was found. - schema: - $ref: ../application-service/definitions/location_batch.yaml - 404: + content: + application/json: + schema: + $ref: ../application-service/definitions/location_batch.yaml + "404": description: No portal rooms were found. - examples: - application/json: { - "errcode": "M_NOT_FOUND" - } - schema: - $ref: definitions/errors/error.yaml + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND" + } tags: - Third-party Lookup "/thirdparty/user/{protocol}": @@ -130,32 +133,38 @@ paths: parameters: - in: path name: protocol - type: string - description: |- - The name of the protocol. + description: The name of the protocol. required: true - x-example: irc + example: irc + schema: + type: string - in: query name: fields... - type: string - description: |- - One or more custom fields that are passed to the AS to help identify the user. + description: One or more custom fields that are passed to the AS to help + identify the user. + schema: + type: string responses: - 200: + "200": description: The Matrix User IDs found with the given parameters. - schema: - $ref: ../application-service/definitions/user_batch.yaml - 404: + content: + application/json: + schema: + $ref: ../application-service/definitions/user_batch.yaml + "404": description: The Matrix User ID was not found - examples: - application/json: { - "errcode": "M_NOT_FOUND" - } - schema: - $ref: definitions/errors/error.yaml + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND" + } tags: - Third-party Lookup - "/thirdparty/location": + /thirdparty/location: get: summary: Reverse-lookup third-party locations given a Matrix room alias. description: |- @@ -167,54 +176,78 @@ paths: parameters: - in: query name: alias - type: string description: The Matrix room alias to look up. required: true - x-example: "#matrix:matrix.org" - responses: - 200: - description: |- - All found third-party locations. + example: "#matrix:matrix.org" schema: - $ref: ../application-service/definitions/location_batch.yaml - 404: + type: string + responses: + "200": + description: All found third-party locations. + content: + application/json: + schema: + $ref: ../application-service/definitions/location_batch.yaml + "404": description: The Matrix room alias was not found - examples: - application/json: { - "errcode": "M_NOT_FOUND" - } - schema: - $ref: definitions/errors/error.yaml + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND" + } tags: - Third-party Lookup - "/thirdparty/user": + /thirdparty/user: get: summary: Reverse-lookup third-party users given a Matrix User ID. - description: |- - Retrieve an array of third-party users from a Matrix User ID. + description: Retrieve an array of third-party users from a Matrix User ID. operationId: queryUserByID security: - accessToken: [] parameters: - in: query name: userid - type: string description: The Matrix User ID to look up. required: true - x-example: "@bob:matrix.org" - responses: - 200: - description: |- - An array of third-party users. + example: "@bob:matrix.org" schema: - $ref: ../application-service/definitions/user_batch.yaml - 404: + type: string + responses: + "200": + description: An array of third-party users. + content: + application/json: + schema: + $ref: ../application-service/definitions/user_batch.yaml + "404": description: The Matrix User ID was not found - examples: - application/json: { - "errcode": "M_NOT_FOUND" - } - schema: - $ref: definitions/errors/error.yaml + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND" + } tags: - Third-party Lookup +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 diff --git a/data/api/client-server/third_party_membership.yaml b/data/api/client-server/third_party_membership.yaml index c6ce230eb..7105ac842 100644 --- a/data/api/client-server/third_party_membership.yaml +++ b/data/api/client-server/third_party_membership.yaml @@ -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 Room Membership API for third-party identifiers" - 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 Room Membership API for third-party identifiers + version: 1.0.0 paths: "/rooms/{roomId}/invite": post: @@ -71,56 +60,64 @@ paths: If a token is requested from the identity server, the homeserver will append a `m.room.third_party_invite` event to the room. - operationId: inviteBy3PID security: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room identifier (not alias) to which to invite the user. required: true - x-example: "!d41d8cd:matrix.org" - - in: body - name: body - required: true + example: "!d41d8cd:matrix.org" schema: - type: object - example: { + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { "id_server": "matrix.org", "id_access_token": "abc123_OpaqueString", "medium": "email", "address": "cheeky@monkey.com" } - properties: - id_server: - type: string - description: The hostname+port of the identity server which should be used for third-party identifier lookups. - id_access_token: - type: string - description: |- - An access token previously registered with the identity server. Servers - can treat this as optional to distinguish between r0.5-compatible clients - and this specification version. - medium: - type: string - description: |- - The kind of address being passed in the address field, for example - `email` (see [the list of recognised values](/appendices/#3pid-types)). - address: - type: string - description: The invitee's third-party identifier. - required: ["id_server", "id_access_token", "medium", "address"] + properties: + id_server: + type: string + description: The hostname+port of the identity server which should be used for + third-party identifier lookups. + id_access_token: + type: string + description: |- + An access token previously registered with the identity server. Servers + can treat this as optional to distinguish between r0.5-compatible clients + and this specification version. + medium: + type: string + description: |- + The kind of address being passed in the address field, for example + `email` (see [the list of recognised values](/appendices/#3pid-types)). + address: + type: string + description: The invitee's third-party identifier. + required: + - id_server + - id_access_token + - medium + - address + required: true responses: - 200: + "200": description: The user has been invited to join the room. - examples: - application/json: { - } - schema: - type: object - 403: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "403": description: |- You do not have permission to invite the user to the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are: @@ -128,14 +125,36 @@ paths: - The invitee is already a member of the room. - The inviter is not currently in the room. - The inviter's power level is insufficient to invite users to the room. - examples: - application/json: { - "errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"} - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "@cheeky_monkey:matrix.org is banned from the room" + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Room membership +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 diff --git a/data/api/client-server/threads_list.yaml b/data/api/client-server/threads_list.yaml index a118d6944..8724b58d7 100644 --- a/data/api/client-server/threads_list.yaml +++ b/data/api/client-server/threads_list.yaml @@ -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 Threads List API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Threads List API + version: 1.0.0 paths: "/rooms/{roomId}/threads": get: @@ -33,7 +22,7 @@ paths: summary: Fetches a list of the threads in a room. description: |- This API is used to paginate through the list of the thread roots in a given room. - + Optionally, the returned list may be filtered according to whether the requesting user has participated in the thread. operationId: getThreadRoots @@ -41,67 +30,97 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The room ID where the thread roots are located. required: true - x-example: "!room:example.org" + example: "!room:example.org" + schema: + type: string - in: query - type: string name: include - enum: [all, participated] description: |- Optional (default `all`) flag to denote which thread roots are of interest to the caller. When `all`, all thread roots found in the room are returned. When `participated`, only thread roots for threads the user has [participated in](/client-server-api/#server-side-aggregation-of-mthread-relationships) will be returned. - x-example: "all" + example: all + schema: + type: string + enum: + - all + - participated - in: query - type: integer name: limit description: |- Optional limit for the maximum number of thread roots to include per response. Must be an integer greater than zero. Servers should apply a default value, and impose a maximum value to avoid resource exhaustion. - x-example: 20 + example: 20 + schema: + type: integer - in: query - type: string name: from description: |- A pagination token from a previous result. When not provided, the server starts paginating from the most recent event visible to the user (as per history visibility rules; topologically). - x-example: "next_batch_token" + example: next_batch_token + schema: + type: string responses: - 200: + "200": + description: A portion of the available thread roots in the room, based on the + filter criteria. + content: + application/json: + schema: + type: object + properties: + chunk: + type: array + description: |- + The thread roots, ordered by the `latest_event` in each event's aggregated children. All events + returned include bundled [aggregations](/client-server-api/#aggregations-of-child-events). + + If the thread root event was sent by an [ignored user](/client-server-api/#ignoring-users), the + event is returned redacted to the caller. This is to simulate the same behaviour of a client doing + aggregation locally on the thread. + items: + $ref: definitions/client_event.yaml + next_batch: + type: string + description: |- + A token to supply to `from` to keep paginating the responses. Not present when there are + no further results. + required: + - chunk + examples: + response: + value: { + "chunk": [ + { + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" + } + ], + "next_batch": "next_batch_token" + } + "400": description: |- - A portion of the available thread roots in the room, based on the filter criteria. - examples: - application/json: { - "chunk": [{ "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" }], - "next_batch": "next_batch_token" - } - schema: - type: object - properties: - chunk: - type: array - description: |- - The thread roots, ordered by the `latest_event` in each event's aggregated children. All events - returned include bundled [aggregations](/client-server-api/#aggregations-of-child-events). + The request was invalid in some way. A meaningful `errcode` + and description error text will be returned. Example reasons for rejection are: - If the thread root event was sent by an [ignored user](/client-server-api/#ignoring-users), the - event is returned redacted to the caller. This is to simulate the same behaviour of a client doing - aggregation locally on the thread. - items: - $ref: "definitions/client_event.yaml" - next_batch: - type: string - description: |- - A token to supply to `from` to keep paginating the responses. Not present when there are - no further results. - required: [chunk] - 403: + - The `from` token is unknown to the server. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_INVALID_PARAM", + "error": "Unknown pagination token" + } + "403": description: |- The user cannot view or peek on the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejection are: @@ -109,29 +128,36 @@ paths: - The room is not set up for peeking. - The user has been banned from the room. - The room does not exist. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "You are not allowed to view this room." - } - schema: - "$ref": "definitions/errors/error.yaml" - 400: - description: |- - The request was invalid in some way. A meaningful `errcode` - and description error text will be returned. Example reasons for rejection are: - - - The `from` token is unknown to the server. - examples: - application/json: { - "errcode": "M_INVALID_PARAM", - "error": "Unknown pagination token" - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You are not allowed to view this room." + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Threads +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/to_device.yaml b/data/api/client-server/to_device.yaml index 266593e1d..d8832fa39 100644 --- a/data/api/client-server/to_device.yaml +++ b/data/api/client-server/to_device.yaml @@ -11,22 +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 Send-to-device 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 Send-to-device API + version: 1.0.0 paths: "/sendToDevice/{eventType}/{txnId}": put: @@ -39,54 +27,72 @@ paths: - accessToken: [] parameters: - in: path - type: string name: eventType description: The type of event to send. required: true - x-example: "m.new_device" + example: m.new_device + schema: + type: string - in: path name: txnId - type: string description: |- The [transaction ID](/client-server-api/#transaction-identifiers) for this event. Clients should generate an ID unique across requests with the same access token; it will be used by the server to ensure idempotency of requests. required: true - x-example: "35" - - in: body - name: body - required: true + example: "35" schema: - type: object - title: body - properties: - messages: - type: object - description: |- - The messages to send. A map from user ID, to a map from - device ID to message body. The device ID may also be `*`, - meaning all known devices for the user. - additionalProperties: + type: string + requestBody: + content: + application/json: + schema: + type: object + title: body + properties: + messages: type: object + description: |- + The messages to send. A map from user ID, to a map from + device ID to message body. The device ID may also be `*`, + meaning all known devices for the user. additionalProperties: type: object - title: EventContent - description: Message content - example: { - "@alice:example.com": { - "TLLBEANAAG": { - "example_content_key": "value" - } - } - } - required: ["messages"] + additionalProperties: + type: object + title: EventContent + description: Message content + example: + "@alice:example.com": + TLLBEANAAG: + example_content_key: value + required: + - messages + required: true responses: - 200: - description: - The message was successfully sent. - examples: - application/json: {} - schema: - type: object + "200": + description: The message was successfully sent. + content: + application/json: + schema: + type: object + examples: + response: + value: {} tags: - Send-to-Device messaging +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 diff --git a/data/api/client-server/typing.yaml b/data/api/client-server/typing.yaml index 65a1225da..4e53cf69c 100644 --- a/data/api/client-server/typing.yaml +++ b/data/api/client-server/typing.yaml @@ -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 Typing 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 Typing API + version: 1.0.0 paths: "/rooms/{roomId}/typing/{userId}": put: @@ -40,48 +29,71 @@ paths: - accessToken: [] parameters: - in: path - type: string name: userId description: The user who has started to type. required: true - x-example: "@alice:example.com" + example: "@alice:example.com" + schema: + type: string - in: path - type: string name: roomId description: The room in which the user is typing. required: true - x-example: "!wefh3sfukhs:example.com" - - in: body - name: typingState - description: The current typing state. - required: true + example: "!wefh3sfukhs:example.com" schema: - type: object - example: { + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { "typing": true, "timeout": 30000 } - properties: - typing: - type: boolean - description: |- - Whether the user is typing or not. If `false`, the `timeout` - key can be omitted. - timeout: - type: integer - description: The length of time in milliseconds to mark this user as typing. - required: ["typing"] + properties: + typing: + type: boolean + description: |- + Whether the user is typing or not. If `false`, the `timeout` + key can be omitted. + timeout: + type: integer + description: The length of time in milliseconds to mark this user as typing. + required: + - typing + description: The current typing state. + required: true responses: - 200: + "200": description: The new typing state was set. - examples: - application/json: { - } - schema: - type: object # empty json object - 429: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml 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 diff --git a/data/api/client-server/users.yaml b/data/api/client-server/users.yaml index ca39e5fe9..67854f087 100644 --- a/data/api/client-server/users.yaml +++ b/data/api/client-server/users.yaml @@ -11,23 +11,12 @@ # 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 User Directory 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 User Directory API + version: 1.0.0 paths: - "/user_directory/search": + /user_directory/search: post: summary: Searches the user directory. description: |- @@ -44,67 +33,93 @@ paths: operationId: searchUserDirectory security: - accessToken: [] - parameters: - - in: body - name: body - required: true - schema: - type: object - properties: - search_term: - type: string - description: The term to search for - example: "foo" - limit: - type: integer - description: The maximum number of results to return. Defaults to 10. - example: 10 - required: ["search_term"] + requestBody: + content: + application/json: + schema: + type: object + properties: + search_term: + type: string + description: The term to search for + example: foo + limit: + type: integer + description: The maximum number of results to return. Defaults to 10. + example: 10 + required: + - search_term + required: true responses: - 200: + "200": description: The results of the search. - examples: - application/json: { - "results": [ - { - "user_id": "@foo:bar.com", - "display_name": "Foo", - "avatar_url": "mxc://bar.com/foo" - } - ], - "limited": false - } - schema: - type: object - required: ["results", "limited"] - properties: - results: - type: array - description: Ordered by rank and then whether or not profile info is available. - items: - title: User - type: object - required: ["user_id"] - properties: - user_id: - type: string - example: "@foo:bar.com" - description: The user's matrix user ID. - display_name: - type: string - example: "Foo" - description: The display name of the user, if one exists. - avatar_url: - type: string - format: uri - example: "mxc://bar.com/foo" - description: The avatar url, as an [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris), if one exists. - limited: - type: boolean - description: Indicates if the result list has been truncated by the limit. - 429: + content: + application/json: + schema: + type: object + required: + - results + - limited + properties: + results: + type: array + description: Ordered by rank and then whether or not profile info is available. + items: + title: User + type: object + required: + - user_id + properties: + user_id: + type: string + example: "@foo:bar.com" + description: The user's matrix user ID. + display_name: + type: string + example: Foo + description: The display name of the user, if one exists. + avatar_url: + type: string + format: uri + example: mxc://bar.com/foo + description: The avatar url, as an [`mxc://` + URI](/client-server-api/#matrix-content-mxc-uris), + if one exists. + limited: + type: boolean + description: Indicates if the result list has been truncated by the limit. + examples: + response: + value: { + "results": [ + { + "user_id": "@foo:bar.com", + "display_name": "Foo", + "avatar_url": "mxc://bar.com/foo" + } + ], + "limited": false + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - User directory +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 diff --git a/data/api/client-server/versions.yaml b/data/api/client-server/versions.yaml index 58c1fbe05..14785e53a 100644 --- a/data/api/client-server/versions.yaml +++ b/data/api/client-server/versions.yaml @@ -11,19 +11,12 @@ # 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 Versions API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client -produces: - - application/json + title: Matrix Client-Server Versions API + version: 1.0.0 paths: - "/versions": + /versions: get: summary: Gets the versions of the specification supported by the server. description: |- @@ -47,33 +40,52 @@ paths: features in their stable releases. operationId: getVersions responses: - 200: + "200": description: The versions supported by the server. - examples: - application/json: { - "versions": ["r0.0.1", "v1.1"], - "unstable_features": { - "org.example.my_feature": true - } - } - schema: - type: object - properties: - versions: - type: array - description: The supported versions. - items: - type: string - description: The supported versions - unstable_features: + content: + application/json: + schema: type: object - description: |- - Experimental features the server supports. Features not listed here, - or the lack of this property all together, indicate that a feature is - not supported. - additionalProperties: - type: boolean - description: Whether or not the namespaced feature is supported. - required: ['versions'] + properties: + versions: + type: array + description: The supported versions. + items: + type: string + description: The supported versions + unstable_features: + type: object + description: |- + Experimental features the server supports. Features not listed here, + or the lack of this property all together, indicate that a feature is + not supported. + additionalProperties: + type: boolean + description: Whether or not the namespaced feature is supported. + required: + - versions + examples: + response: + value: { + "versions": [ + "r0.0.1", + "v1.1" + ], + "unstable_features": { + "org.example.my_feature": true + } + } tags: - Server administration +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client diff --git a/data/api/client-server/voip.yaml b/data/api/client-server/voip.yaml index 6c0d18161..ea9146ecc 100644 --- a/data/api/client-server/voip.yaml +++ b/data/api/client-server/voip.yaml @@ -11,23 +11,12 @@ # 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 Voice over IP 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 Voice over IP API + version: 1.0.0 paths: - "/voip/turnServer": + /voip/turnServer: get: summary: Obtain TURN server credentials. description: |- @@ -37,42 +26,64 @@ paths: security: - accessToken: [] responses: - 200: + "200": description: The TURN server credentials. - examples: - application/json: { - "username":"1443779631:@user:example.com", - "password":"JlKfBy1QwLrO20385QyAtEyIv0=", - "uris":[ - "turn:turn.example.com:3478?transport=udp", - "turn:10.20.30.40:3478?transport=tcp", - "turns:10.20.30.40:443?transport=tcp" - ], - "ttl":86400 - } - schema: - type: object - properties: - username: - type: string - description: |- - The username to use. - password: - type: string - description: |- - The password to use. - uris: - type: array - items: - type: string - description: A list of TURN URIs - ttl: - type: integer - description: The time-to-live in seconds - required: ["username", "password", "uris", "ttl"] - 429: + content: + application/json: + schema: + type: object + properties: + username: + type: string + description: The username to use. + password: + type: string + description: The password to use. + uris: + type: array + items: + type: string + description: A list of TURN URIs + ttl: + type: integer + description: The time-to-live in seconds + required: + - username + - password + - uris + - ttl + examples: + response: + value: { + "username": "1443779631:@user:example.com", + "password": "JlKfBy1QwLrO20385QyAtEyIv0=", + "uris": [ + "turn:turn.example.com:3478?transport=udp", + "turn:10.20.30.40:3478?transport=tcp", + "turns:10.20.30.40:443?transport=tcp" + ], + "ttl": 86400 + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - VOIP +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 diff --git a/data/api/client-server/wellknown.yaml b/data/api/client-server/wellknown.yaml index 9fff7ea78..72de3598d 100644 --- a/data/api/client-server/wellknown.yaml +++ b/data/api/client-server/wellknown.yaml @@ -11,18 +11,12 @@ # 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 Server Discovery API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https -basePath: /.well-known -produces: - - application/json + title: Matrix Client-Server Server Discovery API + version: 1.0.0 paths: - "/matrix/client": + /matrix/client: get: summary: Gets Matrix server discovery information about the domain. description: |- @@ -36,11 +30,25 @@ paths: but by another webserver, to be used for discovering the homeserver URL. operationId: getWellknown responses: - 200: + "200": description: Server discovery information. - schema: - "$ref": "definitions/wellknown/full.yaml" - 404: + content: + application/json: + schema: + $ref: definitions/wellknown/full.yaml + "404": description: No server discovery information available. tags: - Server administration +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /.well-known diff --git a/data/api/client-server/whoami.yaml b/data/api/client-server/whoami.yaml index 727f7e642..342cbeb70 100644 --- a/data/api/client-server/whoami.yaml +++ b/data/api/client-server/whoami.yaml @@ -11,21 +11,12 @@ # 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 Account Identification API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/client/v3 -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Client-Server Account Identification API + version: 1.0.0 paths: - "/account/whoami": + /account/whoami: get: summary: Gets information about the owner of an access token. description: |- @@ -40,61 +31,85 @@ paths: operationId: getTokenOwner security: - accessToken: [] - parameters: [] responses: - 200: - description: - The token belongs to a known user. - examples: - application/json: { - "user_id": "@joe:example.org", - "device_id": "ABC1234" - } - schema: - type: object - required: ["user_id"] - properties: - user_id: - type: string - description: The user ID that owns the access token. - device_id: - x-addedInMatrixVersion: "1.1" - type: string - description: |- - Device ID associated with the access token. If no device - is associated with the access token (such as in the case - of application services) then this field can be omitted. - Otherwise this is required. - is_guest: - x-addedInMatrixVersion: "1.2" - type: boolean - description: |- - When `true`, the user is a [Guest User](#guest-access). When - not present or `false`, the user is presumed to be a non-guest - user. - 401: - description: - The token is not recognised - examples: - application/json: { - "errcode": "M_UNKNOWN_TOKEN", - "error": "Unrecognised access token." - } - schema: - "$ref": "definitions/errors/error.yaml" - 403: - description: - The appservice cannot masquerade as the user or has not registered them. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "Application service has not registered this user." - } - schema: - "$ref": "definitions/errors/error.yaml" - 429: + "200": + description: The token belongs to a known user. + content: + application/json: + schema: + type: object + required: + - user_id + properties: + user_id: + type: string + description: The user ID that owns the access token. + device_id: + x-addedInMatrixVersion: "1.1" + type: string + description: |- + Device ID associated with the access token. If no device + is associated with the access token (such as in the case + of application services) then this field can be omitted. + Otherwise this is required. + is_guest: + x-addedInMatrixVersion: "1.2" + type: boolean + description: |- + When `true`, the user is a [Guest User](#guest-access). When + not present or `false`, the user is presumed to be a non-guest + user. + examples: + response: + value: { + "user_id": "@joe:example.org", + "device_id": "ABC1234" + } + "401": + description: The token is not recognised + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_UNKNOWN_TOKEN", + "error": "Unrecognised access token." + } + "403": + description: The appservice cannot masquerade as the user or has not registered + them. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "Application service has not registered this user." + } + "429": description: This request was rate-limited. - schema: - "$ref": "definitions/errors/rate_limited.yaml" + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml tags: - Session management +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 diff --git a/data/api/identity/v2_associations.yaml b/data/api/identity/v2_associations.yaml index 4a83a34f9..8ed4041aa 100644 --- a/data/api/identity/v2_associations.yaml +++ b/data/api/identity/v2_associations.yaml @@ -12,102 +12,108 @@ # 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 Identity Service Establishing Associations API" - version: "2.0.0" -host: localhost:8090 -schemes: - - https -basePath: /_matrix/identity/v2 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Identity Service Establishing Associations API + version: 2.0.0 paths: - "/3pid/getValidated3pid": + /3pid/getValidated3pid: get: summary: Check whether ownership of a 3pid was validated. - description: |- - Determines if a given 3pid has been validated by a user. + description: Determines if a given 3pid has been validated by a user. operationId: getValidated3pidV2 security: - accessToken: [] parameters: - in: query - type: string name: sid description: The Session ID generated by the `requestToken` call. required: true - x-example: 1234 + example: 1234 + schema: + type: string - in: query - type: string name: client_secret description: The client secret passed to the `requestToken` call. required: true - x-example: monkeys_are_GREAT + example: monkeys_are_GREAT + schema: + type: string responses: - 200: + "200": description: Validation information for the session. - examples: - application/json: { - "medium": "email", - "validated_at": 1457622739026, - "address": "louise@bobs.burgers" - } - schema: - type: object - properties: - medium: - type: string - description: The medium type of the 3pid. - address: - type: string - description: The address of the 3pid being looked up. - validated_at: - type: integer - format: int64 - description: |- - Timestamp, in milliseconds, indicating the time that the 3pid - was validated. - required: ['medium', 'address', 'validated_at'] - 400: + content: + application/json: + schema: + type: object + properties: + medium: + type: string + description: The medium type of the 3pid. + address: + type: string + description: The address of the 3pid being looked up. + validated_at: + type: integer + format: int64 + description: |- + Timestamp, in milliseconds, indicating the time that the 3pid + was validated. + required: + - medium + - address + - validated_at + examples: + response: + value: { + "medium": "email", + "validated_at": 1457622739026, + "address": "louise@bobs.burgers" + } + "400": description: |- The session has not been validated. If the session has not been validated, then `errcode` will be `M_SESSION_NOT_VALIDATED`. If the session has timed out, then `errcode` will be `M_SESSION_EXPIRED`. - examples: - application/json: { - "errcode": "M_SESSION_NOT_VALIDATED", - "error": "This validation session has not yet been completed" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 404: - description: The Session ID or client secret were not found. - examples: - application/json: { - "errcode": "M_NO_VALID_SESSION", - "error": "No valid session was found matching that sid and client secret" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 403: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_SESSION_NOT_VALIDATED", + "error": "This validation session has not yet been completed" + } + "403": description: | The user must do something in order to use this endpoint. One example is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). - examples: - application/json: { - "errcode": "M_TERMS_NOT_SIGNED", - "error": "Please accept our updated terms of service before continuing" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - "/3pid/bind": + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } + "404": + description: The Session ID or client secret were not found. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NO_VALID_SESSION", + "error": "No valid session was found matching that sid and client secret" + } + /3pid/bind: post: summary: Publish an association between a session and a Matrix user ID. description: |- @@ -123,119 +129,136 @@ paths: operationId: bindV2 security: - accessToken: [] - parameters: - - in: body - name: body - schema: - type: object - example: { - "sid": "1234", - "client_secret": "monkeys_are_GREAT", - "mxid": "@ears:matrix.org" - } - properties: - sid: - type: string - description: The Session ID generated by the `requestToken` call. - client_secret: - type: string - description: The client secret passed to the `requestToken` call. - mxid: - type: string - description: The Matrix user ID to associate with the 3pids. - required: ["sid", "client_secret", "mxid"] + requestBody: + content: + application/json: + schema: + type: object + example: { + "sid": "1234", + "client_secret": "monkeys_are_GREAT", + "mxid": "@ears:matrix.org" + } + properties: + sid: + type: string + description: The Session ID generated by the `requestToken` call. + client_secret: + type: string + description: The client secret passed to the `requestToken` call. + mxid: + type: string + description: The Matrix user ID to associate with the 3pids. + required: + - sid + - client_secret + - mxid responses: - 200: + "200": description: The association was published. - examples: - application/json: { - "address": "louise@bobs.burgers", - "medium": "email", - "mxid": "@ears:matrix.org", - "not_before": 1428825849161, - "not_after": 4582425849161, - "ts": 1428825849161, - "signatures": { - "matrix.org": { - "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ" - } - } - } - schema: - type: object - properties: - address: - type: string - description: The 3pid address of the user being looked up. - medium: - type: string - description: The medium type of the 3pid. - mxid: - type: string - description: The Matrix user ID associated with the 3pid. - not_before: - type: integer - format: int64 - description: A unix timestamp before which the association is not known to be valid. - not_after: - type: integer - format: int64 - description: A unix timestamp after which the association is not known to be valid. - ts: - type: integer - format: int64 - description: The unix timestamp at which the association was verified. - signatures: + content: + application/json: + schema: type: object - description: |- - The signatures of the verifying identity servers which show that the - association should be trusted, if you trust the verifying identity - services. - allOf: - - $ref: "../../schemas/server-signatures.yaml" - required: - - address - - medium - - mxid - - not_before - - not_after - - ts - - signatures - 400: + properties: + address: + type: string + description: The 3pid address of the user being looked up. + medium: + type: string + description: The medium type of the 3pid. + mxid: + type: string + description: The Matrix user ID associated with the 3pid. + not_before: + type: integer + format: int64 + description: A unix timestamp before which the association is not known to be + valid. + not_after: + type: integer + format: int64 + description: A unix timestamp after which the association is not known to be + valid. + ts: + type: integer + format: int64 + description: The unix timestamp at which the association was verified. + signatures: + type: object + description: |- + The signatures of the verifying identity servers which show that the + association should be trusted, if you trust the verifying identity + services. + allOf: + - $ref: ../../schemas/server-signatures.yaml + required: + - address + - medium + - mxid + - not_before + - not_after + - ts + - signatures + examples: + response: + value: { + "address": "louise@bobs.burgers", + "medium": "email", + "mxid": "@ears:matrix.org", + "not_before": 1428825849161, + "not_after": 4582425849161, + "ts": 1428825849161, + "signatures": { + "matrix.org": { + "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ" + } + } + } + "400": description: |- The association was not published. If the session has not been validated, then `errcode` will be `M_SESSION_NOT_VALIDATED`. If the session has timed out, then `errcode` will be `M_SESSION_EXPIRED`. - examples: - application/json: { - "errcode": "M_SESSION_NOT_VALIDATED", - "error": "This validation session has not yet been completed" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 404: - description: The Session ID or client secret were not found - examples: - application/json: { - "errcode": "M_NO_VALID_SESSION", - "error": "No valid session was found matching that sid and client secret" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 403: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_SESSION_NOT_VALIDATED", + "error": "This validation session has not yet been completed" + } + "403": description: | The user must do something in order to use this endpoint. One example is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). - examples: - application/json: { - "errcode": "M_TERMS_NOT_SIGNED", - "error": "Please accept our updated terms of service before continuing" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - "/3pid/unbind": + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } + "404": + description: The Session ID or client secret were not found + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NO_VALID_SESSION", + "error": "No valid session was found matching that sid and client secret" + } + /3pid/unbind: post: summary: Remove an association between a session and a Matrix user ID. description: |- @@ -257,65 +280,67 @@ paths: operationId: unbindV2 security: - accessToken: [] - parameters: - - in: body - name: body - schema: - type: object - example: { - "sid": "1234", - "client_secret": "monkeys_are_GREAT", - "mxid": "@ears:example.org", - "threepid": { - "medium": "email", - "address": "monkeys_have_ears@example.org" + requestBody: + content: + application/json: + schema: + type: object + example: { + "sid": "1234", + "client_secret": "monkeys_are_GREAT", + "mxid": "@ears:example.org", + "threepid": { + "medium": "email", + "address": "monkeys_have_ears@example.org" + } } - } - properties: - sid: - type: string - description: The Session ID generated by the `requestToken` call. - client_secret: - type: string - description: The client secret passed to the `requestToken` call. - mxid: - type: string - description: The Matrix user ID to remove from the 3pids. - threepid: - type: object - title: 3PID - description: |- - The 3PID to remove. Must match the 3PID used to generate the session - if using `sid` and `client_secret` to authenticate this request. - properties: - medium: - type: string - description: |- - A medium from the [3PID Types](/appendices/#3pid-types) Appendix, matching the medium - of the identifier to unbind. - address: - type: string - description: The 3PID address to remove. - required: ['medium', 'address'] - required: ["threepid", "mxid"] + properties: + sid: + type: string + description: The Session ID generated by the `requestToken` call. + client_secret: + type: string + description: The client secret passed to the `requestToken` call. + mxid: + type: string + description: The Matrix user ID to remove from the 3pids. + threepid: + type: object + title: 3PID + description: |- + The 3PID to remove. Must match the 3PID used to generate the session + if using `sid` and `client_secret` to authenticate this request. + properties: + medium: + type: string + description: |- + A medium from the [3PID Types](/appendices/#3pid-types) Appendix, matching the medium + of the identifier to unbind. + address: + type: string + description: The 3PID address to remove. + required: + - medium + - address + required: + - threepid + - mxid responses: - 200: + "200": description: The association was successfully removed. - examples: - application/json: {} - schema: - type: object - 400: - description: |- - If the response body is not a JSON Matrix error, the identity server - does not support unbinds. If a JSON Matrix error is in the response - body, the requesting party should respect the error. - 404: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "400": description: |- If the response body is not a JSON Matrix error, the identity server does not support unbinds. If a JSON Matrix error is in the response body, the requesting party should respect the error. - 403: + "403": description: |- The credentials supplied to authenticate the request were invalid. This may also be returned if the identity server does not support @@ -324,15 +349,38 @@ paths: Another common error code is `M_TERMS_NOT_SIGNED` where the user needs to [agree to more terms](/identity-service-api/#terms-of-service) in order to continue. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "Invalid homeserver signature" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 501: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "Invalid homeserver signature" + } + "404": + description: |- + If the response body is not a JSON Matrix error, the identity server + does not support unbinds. If a JSON Matrix error is in the response + body, the requesting party should respect the error. + "501": description: |- If the response body is not a JSON Matrix error, the identity server does not support unbinds. If a JSON Matrix error is in the response body, the requesting party should respect the error. +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8090 + basePath: + default: /_matrix/identity/v2 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/identity/v2_auth.yaml b/data/api/identity/v2_auth.yaml index b5d1a41cc..64433f81d 100644 --- a/data/api/identity/v2_auth.yaml +++ b/data/api/identity/v2_auth.yaml @@ -11,22 +11,12 @@ # 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 Identity Service Authentication API" - version: "2.0.0" -host: localhost:8090 -schemes: - - https -basePath: /_matrix/identity/v2 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Identity Service Authentication API + version: 2.0.0 paths: - "/account/register": + /account/register: post: summary: Exchanges an OpenID token for an access token. description: |- @@ -34,64 +24,74 @@ paths: access the identity server. The request body is the same as the values returned by `/openid/request_token` in the Client-Server API. operationId: registerAccount - parameters: - - in: body - name: body - schema: - $ref: "../client-server/definitions/openid_token.yaml" + requestBody: + content: + application/json: + schema: + $ref: ../client-server/definitions/openid_token.yaml responses: - 200: + "200": description: |- A token which can be used to authenticate future requests to the identity server. - examples: - application/json: { - "token": "abc123_OpaqueString" - } - schema: - type: object - properties: - token: - type: string - description: |- - An opaque string representing the token to authenticate future - requests to the identity server with. - required: ['token'] - "/account": + content: + application/json: + schema: + type: object + properties: + token: + type: string + description: |- + An opaque string representing the token to authenticate future + requests to the identity server with. + required: + - token + examples: + response: + value: { + "token": "abc123_OpaqueString" + } + /account: get: summary: Gets account holder information for a given token. - description: |- - Gets information about what user owns the access token used in the request. + description: Gets information about what user owns the access token used in the + request. operationId: getAccount security: - accessToken: [] - parameters: [] responses: - 200: + "200": description: The token holder's information. - examples: - application/json: { - "user_id": "@alice:example.org" - } - schema: - type: object - properties: - user_id: - type: string - description: The user ID which registered the token. - required: ['user_id'] - 403: + content: + application/json: + schema: + type: object + properties: + user_id: + type: string + description: The user ID which registered the token. + required: + - user_id + examples: + response: + value: { + "user_id": "@alice:example.org" + } + "403": description: | The user must do something in order to use this endpoint. One example is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). - examples: - application/json: { - "errcode": "M_TERMS_NOT_SIGNED", - "error": "Please accept our updated terms of service before continuing" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - "/account/logout": + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } + /account/logout: post: summary: Logs out an access token, rendering it unusable. description: |- @@ -100,32 +100,54 @@ paths: operationId: logout security: - accessToken: [] - parameters: [] responses: - 200: + "200": description: The token was successfully logged out. - examples: - application/json: {} - schema: - type: object - 401: - description: |- - The token is not registered or is otherwise unknown to the server. - examples: - application/json: { - "errcode": "M_UNKNOWN_TOKEN", - "error": "Unrecognised access token" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 403: + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "401": + description: The token is not registered or is otherwise unknown to the server. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_UNKNOWN_TOKEN", + "error": "Unrecognised access token" + } + "403": description: | The user must do something in order to use this endpoint. One example is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). - examples: - application/json: { - "errcode": "M_TERMS_NOT_SIGNED", - "error": "Please accept our updated terms of service before continuing" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8090 + basePath: + default: /_matrix/identity/v2 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/identity/v2_email_associations.yaml b/data/api/identity/v2_email_associations.yaml index 600fea41f..0bd31b529 100644 --- a/data/api/identity/v2_email_associations.yaml +++ b/data/api/identity/v2_email_associations.yaml @@ -12,22 +12,12 @@ # 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 Identity Service Email Associations API" - version: "2.0.0" -host: localhost:8090 -schemes: - - https -basePath: /_matrix/identity/v2 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Identity Service Email Associations API + version: 2.0.0 paths: - "/validate/email/requestToken": + /validate/email/requestToken: post: summary: Request a token for validating an email address. description: |- @@ -51,41 +41,49 @@ paths: operationId: emailRequestTokenV2 security: - accessToken: [] - parameters: - - in: body - name: body - schema: - $ref: "definitions/request_email_validation.yaml" + requestBody: + content: + application/json: + schema: + $ref: definitions/request_email_validation.yaml responses: - 200: + "200": description: Session created. - schema: - $ref: "definitions/sid.yaml" - 400: + content: + application/json: + schema: + $ref: definitions/sid.yaml + "400": description: | An error occurred. Some possible errors are: - `M_INVALID_EMAIL`: The email address provided was invalid. - `M_EMAIL_SEND_ERROR`: The validation email could not be sent. - examples: - application/json: { - "errcode": "M_INVALID_EMAIL", - "error": "The email address is not valid" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 403: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_INVALID_EMAIL", + "error": "The email address is not valid" + } + "403": description: | The user must do something in order to use this endpoint. One example is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). - examples: - application/json: { - "errcode": "M_TERMS_NOT_SIGNED", - "error": "Please accept our updated terms of service before continuing" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - "/validate/email/submitToken": + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } + /validate/email/submitToken: post: summary: Validate ownership of an email address. description: |- @@ -110,53 +108,63 @@ paths: operationId: emailSubmitTokenPostV2 security: - accessToken: [] - parameters: - - in: body - name: body - schema: - type: object - example: { - "sid": "1234", - "client_secret": "monkeys_are_GREAT", - "token": "atoken" - } - properties: - sid: - type: string - description: The session ID, generated by the `requestToken` call. - client_secret: - type: string - description: The client secret that was supplied to the `requestToken` call. - token: - type: string - description: The token generated by the `requestToken` call and emailed to the user. - required: ["sid", "client_secret", "token"] + requestBody: + content: + application/json: + schema: + type: object + example: { + "sid": "1234", + "client_secret": "monkeys_are_GREAT", + "token": "atoken" + } + properties: + sid: + type: string + description: The session ID, generated by the `requestToken` call. + client_secret: + type: string + description: The client secret that was supplied to the `requestToken` call. + token: + type: string + description: The token generated by the `requestToken` call and emailed to the + user. + required: + - sid + - client_secret + - token responses: - 200: - description: - The success of the validation. - examples: - application/json: { - "success": true - } - schema: - type: object - properties: - success: - type: boolean - description: Whether the validation was successful or not. - required: ['success'] - 403: + "200": + description: The success of the validation. + content: + application/json: + schema: + type: object + properties: + success: + type: boolean + description: Whether the validation was successful or not. + required: + - success + examples: + response: + value: { + "success": true + } + "403": description: | The user must do something in order to use this endpoint. One example is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). - examples: - application/json: { - "errcode": "M_TERMS_NOT_SIGNED", - "error": "Please accept our updated terms of service before continuing" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } get: summary: Validate ownership of an email address. description: |- @@ -175,42 +183,63 @@ paths: - accessToken: [] parameters: - in: query - type: string name: sid required: true description: The session ID, generated by the `requestToken` call. - x-example: 1234 + example: 1234 + schema: + type: string - in: query - type: string name: client_secret required: true description: The client secret that was supplied to the `requestToken` call. - x-example: monkeys_are_GREAT + example: monkeys_are_GREAT + schema: + type: string - in: query - type: string name: token required: true - description: The token generated by the `requestToken` call and emailed to the user. - x-example: atoken + description: The token generated by the `requestToken` call and emailed to the + user. + example: atoken + schema: + type: string responses: - 200: + "200": description: Email address is validated. - "3xx": + "403": + description: | + The user must do something in order to use this endpoint. One example + is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } + "3XX": description: |- Email address is validated, and the `next_link` parameter was provided to the `requestToken` call. The user must be redirected to the URL provided by the `next_link` parameter. - "4xx": - description: - Validation failed. - 403: - description: | - The user must do something in order to use this endpoint. One example - is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). - examples: - application/json: { - "errcode": "M_TERMS_NOT_SIGNED", - "error": "Please accept our updated terms of service before continuing" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" + "4XX": + description: Validation failed. +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8090 + basePath: + default: /_matrix/identity/v2 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/identity/v2_invitation_signing.yaml b/data/api/identity/v2_invitation_signing.yaml index 2308dc7b6..ae05c6fdf 100644 --- a/data/api/identity/v2_invitation_signing.yaml +++ b/data/api/identity/v2_invitation_signing.yaml @@ -12,22 +12,12 @@ # 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 Identity Service Ephemeral Invitation Signing API" - version: "2.0.0" -host: localhost:8090 -schemes: - - https -basePath: /_matrix/identity/v2 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Identity Service Ephemeral Invitation Signing API + version: 2.0.0 paths: - "/sign-ed25519": + /sign-ed25519: post: summary: Sign invitation details description: |- @@ -38,76 +28,108 @@ paths: operationId: blindlySignStuffV2 security: - accessToken: [] - parameters: - - in: body - name: body - schema: - type: object - example: { - "mxid": "@foo:bar.com", - "token": "sometoken", - "private_key": "base64encodedkey" - } - properties: - mxid: - type: string - description: The Matrix user ID of the user accepting the invitation. - token: - type: string - description: The token from the call to `store-invite`. - private_key: - type: string - description: The private key, encoded as [Unpadded base64](/appendices/#unpadded-base64). - required: ["mxid", "token", "private_key"] + requestBody: + content: + application/json: + schema: + type: object + example: { + "mxid": "@foo:bar.com", + "token": "sometoken", + "private_key": "base64encodedkey" + } + properties: + mxid: + type: string + description: The Matrix user ID of the user accepting the invitation. + token: + type: string + description: The token from the call to `store-invite`. + private_key: + type: string + description: The private key, encoded as [Unpadded + base64](/appendices/#unpadded-base64). + required: + - mxid + - token + - private_key responses: - 200: + "200": description: The signed JSON of the mxid, sender, and token. - schema: - type: object - properties: - mxid: - type: string - description: The Matrix user ID of the user accepting the invitation. - sender: - type: string - description: The Matrix user ID of the user who sent the invitation. - signatures: + content: + application/json: + schema: type: object - description: The signature of the mxid, sender, and token. - allOf: - - $ref: "../../schemas/server-signatures.yaml" - token: - type: string - description: The token for the invitation. - required: ['mxid', 'sender', 'signatures', 'token'] - examples: - application/json: { - "mxid": "@foo:bar.com", - "sender": "@baz:bar.com", - "signatures": { - "my.id.server": { - "ed25519:0": "def987" - } - }, - "token": "abc123" - } - 404: - description: The token was not found. - examples: - application/json: { - "errcode": "M_UNRECOGNIZED", - "error": "Didn't recognize token" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 403: + properties: + mxid: + type: string + description: The Matrix user ID of the user accepting the invitation. + sender: + type: string + description: The Matrix user ID of the user who sent the invitation. + signatures: + type: object + description: The signature of the mxid, sender, and token. + allOf: + - $ref: ../../schemas/server-signatures.yaml + token: + type: string + description: The token for the invitation. + required: + - mxid + - sender + - signatures + - token + examples: + response: + value: { + "mxid": "@foo:bar.com", + "sender": "@baz:bar.com", + "signatures": { + "my.id.server": { + "ed25519:0": "def987" + } + }, + "token": "abc123" + } + "403": description: | The user must do something in order to use this endpoint. One example is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). - examples: - application/json: { - "errcode": "M_TERMS_NOT_SIGNED", - "error": "Please accept our updated terms of service before continuing" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } + "404": + description: The token was not found. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_UNRECOGNIZED", + "error": "Didn't recognize token" + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8090 + basePath: + default: /_matrix/identity/v2 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/identity/v2_lookup.yaml b/data/api/identity/v2_lookup.yaml index d5e9352c1..ce716abd9 100644 --- a/data/api/identity/v2_lookup.yaml +++ b/data/api/identity/v2_lookup.yaml @@ -15,22 +15,12 @@ # 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 Identity Service Lookup API" - version: "2.0.0" -host: localhost:8090 -schemes: - - https -basePath: /_matrix/identity/v2 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Identity Service Lookup API + version: 2.0.0 paths: - "/hash_details": + /hash_details: get: summary: Gets hash function information from the server. description: |- @@ -39,33 +29,39 @@ paths: operationId: getHashDetails security: - accessToken: [] - parameters: [] responses: - 200: + "200": description: The hash function information. - examples: - application/json: { - "lookup_pepper": "matrixrocks", - "algorithms": ["none", "sha256"] - } - schema: - type: object - properties: - lookup_pepper: - type: string - description: |- - The pepper the client MUST use in hashing identifiers, and MUST - supply to the `/lookup` endpoint when performing lookups. + content: + application/json: + schema: + type: object + properties: + lookup_pepper: + type: string + description: |- + The pepper the client MUST use in hashing identifiers, and MUST + supply to the `/lookup` endpoint when performing lookups. - Servers SHOULD rotate this string often. - algorithms: - type: array - items: - type: string - description: |- - The algorithms the server supports. Must contain at least `sha256`. - required: ['lookup_pepper', 'algorithms'] - "/lookup": + Servers SHOULD rotate this string often. + algorithms: + type: array + items: + type: string + description: The algorithms the server supports. Must contain at least `sha256`. + required: + - lookup_pepper + - algorithms + examples: + response: + value: { + "lookup_pepper": "matrixrocks", + "algorithms": [ + "none", + "sha256" + ] + } + /lookup: post: summary: Look up Matrix User IDs for a set of 3PIDs. description: |- @@ -75,78 +71,95 @@ paths: operationId: lookupUsersV2 security: - accessToken: [] - parameters: - - in: body - name: body - schema: - type: object - properties: - algorithm: - type: string - description: |- - The algorithm the client is using to encode the `addresses`. This - should be one of the available options from `/hash_details`. - example: "sha256" - pepper: - type: string - description: |- - The pepper from `/hash_details`. This is required even when the - `algorithm` does not make use of it. - example: "matrixrocks" - addresses: - type: array - items: + requestBody: + content: + application/json: + schema: + type: object + properties: + algorithm: + type: string + description: |- + The algorithm the client is using to encode the `addresses`. This + should be one of the available options from `/hash_details`. + example: sha256 + pepper: type: string - description: |- - The addresses to look up. The format of the entries here depend on - the `algorithm` used. Note that queries which have been incorrectly - hashed or formatted will lead to no matches. + description: |- + The pepper from `/hash_details`. This is required even when the + `algorithm` does not make use of it. + example: matrixrocks + addresses: + type: array + items: + type: string + description: |- + The addresses to look up. The format of the entries here depend on + the `algorithm` used. Note that queries which have been incorrectly + hashed or formatted will lead to no matches. - Note that addresses are case sensitive: review the - [3PID Types](/appendices#3pid-types) to verify the intended case an - identifier should be prior to submission/hashing. - example: [ - "4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc", - "nlo35_T5fzSGZzJApqu8lgIudJvmOQtDaHtr-I4rU7I" - ] - required: ['algorithm', 'pepper', 'addresses'] + Note that addresses are case sensitive: review the + [3PID Types](/appendices#3pid-types) to verify the intended case an + identifier should be prior to submission/hashing. + example: + - 4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc + - nlo35_T5fzSGZzJApqu8lgIudJvmOQtDaHtr-I4rU7I + required: + - algorithm + - pepper + - addresses responses: - 200: - description: - The associations for any matched `addresses`. - examples: - application/json: { - "mappings": { - "4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc": "@alice:example.org" - } - } - schema: - type: object - properties: - mappings: + "200": + description: The associations for any matched `addresses`. + content: + application/json: + schema: type: object - description: |- - Any applicable mappings of `addresses` to Matrix User IDs. Addresses - which do not have associations will not be included, which can make - this property be an empty object. - title: AssociatedMappings - additionalProperties: - type: string - required: ['mappings'] - 400: - description: - The client's request was invalid in some way. One possible problem could - be the `pepper` being invalid after the server has rotated it - this is - presented with the `M_INVALID_PEPPER` error code. Clients SHOULD make - a call to `/hash_details` to get a new pepper in this scenario, being - careful to avoid retry loops. - - `M_INVALID_PARAM` can also be returned to indicate the client supplied - an `algorithm` that is unknown to the server. - examples: - application/json: { - "errcode": "M_INVALID_PEPPER", - "error": "Unknown or invalid pepper - has it been rotated?" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" + properties: + mappings: + type: object + description: |- + Any applicable mappings of `addresses` to Matrix User IDs. Addresses + which do not have associations will not be included, which can make + this property be an empty object. + title: AssociatedMappings + additionalProperties: + type: string + required: + - mappings + examples: + response: + value: { + "mappings": { + "4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc": "@alice:example.org" + } + } + "400": + description: |- + The client's request was invalid in some way. One possible problem could be the `pepper` being invalid after the server has rotated it - this is presented with the `M_INVALID_PEPPER` error code. Clients SHOULD make a call to `/hash_details` to get a new pepper in this scenario, being careful to avoid retry loops. + `M_INVALID_PARAM` can also be returned to indicate the client supplied an `algorithm` that is unknown to the server. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_INVALID_PEPPER", + "error": "Unknown or invalid pepper - has it been rotated?" + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8090 + basePath: + default: /_matrix/identity/v2 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/identity/v2_phone_associations.yaml b/data/api/identity/v2_phone_associations.yaml index 85b523e4b..f887be263 100644 --- a/data/api/identity/v2_phone_associations.yaml +++ b/data/api/identity/v2_phone_associations.yaml @@ -12,22 +12,12 @@ # 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 Identity Service Phone Number Associations API" - version: "2.0.0" -host: localhost:8090 -schemes: - - https -basePath: /_matrix/identity/v2 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Identity Service Phone Number Associations API + version: 2.0.0 paths: - "/validate/msisdn/requestToken": + /validate/msisdn/requestToken: post: summary: Request a token for validating a phone number. description: |- @@ -51,17 +41,19 @@ paths: operationId: msisdnRequestTokenV2 security: - accessToken: [] - parameters: - - in: body - name: body - schema: - $ref: "definitions/request_msisdn_validation.yaml" + requestBody: + content: + application/json: + schema: + $ref: definitions/request_msisdn_validation.yaml responses: - 200: + "200": description: Session created. - schema: - $ref: "definitions/sid.yaml" - 400: + content: + application/json: + schema: + $ref: definitions/sid.yaml + "400": description: | An error occurred. Some possible errors are: @@ -69,25 +61,31 @@ paths: - `M_SEND_ERROR`: The validation SMS could not be sent. - `M_DESTINATION_REJECTED`: The identity server cannot deliver an SMS to the provided country or region. - examples: - application/json: { - "errcode": "M_INVALID_ADDRESS", - "error": "The phone number is not valid" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 403: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_INVALID_ADDRESS", + "error": "The phone number is not valid" + } + "403": description: | The user must do something in order to use this endpoint. One example is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). - examples: - application/json: { - "errcode": "M_TERMS_NOT_SIGNED", - "error": "Please accept our updated terms of service before continuing" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - "/validate/msisdn/submitToken": + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } + /validate/msisdn/submitToken: post: summary: Validate ownership of a phone number. description: |- @@ -112,53 +110,63 @@ paths: operationId: msisdnSubmitTokenPostV2 security: - accessToken: [] - parameters: - - in: body - name: body - schema: - type: object - example: { - "sid": "1234", - "client_secret": "monkeys_are_GREAT", - "token": "atoken" - } - properties: - sid: - type: string - description: The session ID, generated by the `requestToken` call. - client_secret: - type: string - description: The client secret that was supplied to the `requestToken` call. - token: - type: string - description: The token generated by the `requestToken` call and sent to the user. - required: ["sid", "client_secret", "token"] + requestBody: + content: + application/json: + schema: + type: object + example: { + "sid": "1234", + "client_secret": "monkeys_are_GREAT", + "token": "atoken" + } + properties: + sid: + type: string + description: The session ID, generated by the `requestToken` call. + client_secret: + type: string + description: The client secret that was supplied to the `requestToken` call. + token: + type: string + description: The token generated by the `requestToken` call and sent to the + user. + required: + - sid + - client_secret + - token responses: - 200: - description: - The success of the validation. - examples: - application/json: { - "success": true - } - schema: - type: object - properties: - success: - type: boolean - description: Whether the validation was successful or not. - required: ['success'] - 403: + "200": + description: The success of the validation. + content: + application/json: + schema: + type: object + properties: + success: + type: boolean + description: Whether the validation was successful or not. + required: + - success + examples: + response: + value: { + "success": true + } + "403": description: | The user must do something in order to use this endpoint. One example is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). - examples: - application/json: { - "errcode": "M_TERMS_NOT_SIGNED", - "error": "Please accept our updated terms of service before continuing" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } get: summary: Validate ownership of a phone number. description: |- @@ -177,42 +185,62 @@ paths: - accessToken: [] parameters: - in: query - type: string name: sid required: true description: The session ID, generated by the `requestToken` call. - x-example: 1234 + example: 1234 + schema: + type: string - in: query - type: string name: client_secret required: true description: The client secret that was supplied to the `requestToken` call. - x-example: monkeys_are_GREAT + example: monkeys_are_GREAT + schema: + type: string - in: query - type: string name: token required: true description: The token generated by the `requestToken` call and sent to the user. - x-example: atoken + example: atoken + schema: + type: string responses: - 200: + "200": description: Phone number is validated. - "3xx": + "403": + description: | + The user must do something in order to use this endpoint. One example + is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } + "3XX": description: |- Phone number address is validated, and the `next_link` parameter was provided to the `requestToken` call. The user must be redirected to the URL provided by the `next_link` parameter. - "4xx": - description: - Validation failed. - 403: - description: | - The user must do something in order to use this endpoint. One example - is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). - examples: - application/json: { - "errcode": "M_TERMS_NOT_SIGNED", - "error": "Please accept our updated terms of service before continuing" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" + "4XX": + description: Validation failed. +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8090 + basePath: + default: /_matrix/identity/v2 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/identity/v2_ping.yaml b/data/api/identity/v2_ping.yaml index e056e3211..8e8044b2d 100644 --- a/data/api/identity/v2_ping.yaml +++ b/data/api/identity/v2_ping.yaml @@ -13,19 +13,12 @@ # 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 Identity Service Ping API" - version: "2.0.0" -host: localhost:8090 -schemes: - - https -basePath: /_matrix/identity -produces: - - application/json + title: Matrix Identity Service Ping API + version: 2.0.0 paths: - "/v2": + /v2: get: summary: Checks that an identity server is available at this API endpoint. description: |- @@ -38,9 +31,24 @@ paths: by entities acting as a client for the identity server. operationId: pingV2 responses: - 200: + "200": description: An identity server is ready to serve requests. - examples: - application/json: {} - schema: - type: object + content: + application/json: + schema: + type: object + examples: + response: + value: {} +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8090 + basePath: + default: /_matrix/identity diff --git a/data/api/identity/v2_pubkey.yaml b/data/api/identity/v2_pubkey.yaml index 68facd681..2aaf5f8e0 100644 --- a/data/api/identity/v2_pubkey.yaml +++ b/data/api/identity/v2_pubkey.yaml @@ -12,61 +12,58 @@ # 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 Identity Service Public Key API" - version: "2.0.0" -host: localhost:8090 -schemes: - - https -basePath: /_matrix/identity/v2 -consumes: - - application/json -produces: - - application/json + title: Matrix Identity Service Public Key API + version: 2.0.0 paths: "/pubkey/{keyId}": get: summary: Get a public key. - description: |- - Get the public key for the passed key ID. + description: Get the public key for the passed key ID. operationId: getPubKeyV2 parameters: - in: path - type: string name: keyId required: true description: |- The ID of the key. This should take the form algorithm:identifier where algorithm identifies the signing algorithm, and the identifier is an opaque string. - x-example: "ed25519:0" - responses: - 200: - description: - The public key exists. - examples: - application/json: { - "public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c" - } - schema: - type: object - properties: - public_key: - type: string - description: Unpadded Base64 encoded public key. - required: ['public_key'] - 404: - description: - The public key was not found. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "The public key was not found" - } + example: ed25519:0 schema: - $ref: "../client-server/definitions/errors/error.yaml" - "/pubkey/isvalid": + type: string + responses: + "200": + description: The public key exists. + content: + application/json: + schema: + type: object + properties: + public_key: + type: string + description: Unpadded Base64 encoded public key. + required: + - public_key + examples: + response: + value: { + "public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c" + } + "404": + description: The public key was not found. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "The public key was not found" + } + /pubkey/isvalid: get: summary: Check whether a long-term public key is valid. description: |- @@ -75,53 +72,70 @@ paths: operationId: isPubKeyValidV2 parameters: - in: query - type: string name: public_key required: true - description: |- - The unpadded base64-encoded public key to check. - x-example: "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c" - responses: - 200: - description: - The validity of the public key. - examples: - application/json: { - "valid": true - } + description: The unpadded base64-encoded public key to check. + example: VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c schema: - type: object - properties: - valid: - type: boolean - description: Whether the public key is recognised and is currently valid. - required: ['valid'] - "/pubkey/ephemeral/isvalid": + type: string + responses: + "200": + description: The validity of the public key. + content: + application/json: + schema: + type: object + properties: + valid: + type: boolean + description: Whether the public key is recognised and is currently valid. + required: + - valid + examples: + response: + value: { + "valid": true + } + /pubkey/ephemeral/isvalid: get: summary: Check whether a short-term public key is valid. - description: |- - Check whether a short-term public key is valid. + description: Check whether a short-term public key is valid. operationId: isEphemeralPubKeyValidV2 parameters: - in: query - type: string name: public_key required: true - description: |- - The unpadded base64-encoded public key to check. - x-example: "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c" - responses: - 200: - description: - The validity of the public key. - examples: - application/json: { - "valid": true - } + description: The unpadded base64-encoded public key to check. + example: VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c schema: - type: object - properties: - valid: - type: boolean - description: Whether the public key is recognised and is currently valid. - required: ['valid'] + type: string + responses: + "200": + description: The validity of the public key. + content: + application/json: + schema: + type: object + properties: + valid: + type: boolean + description: Whether the public key is recognised and is currently valid. + required: + - valid + examples: + response: + value: { + "valid": true + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8090 + basePath: + default: /_matrix/identity/v2 diff --git a/data/api/identity/v2_store_invite.yaml b/data/api/identity/v2_store_invite.yaml index 163081bb8..230dd503d 100644 --- a/data/api/identity/v2_store_invite.yaml +++ b/data/api/identity/v2_store_invite.yaml @@ -12,22 +12,12 @@ # 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 Identity Service Store Invitations API" - version: "2.0.0" -host: localhost:8090 -schemes: - - https -basePath: /_matrix/identity/v2 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Identity Service Store Invitations API + version: 2.0.0 paths: - "/store-invite": + /store-invite: post: summary: Store pending invitations to a user's 3pid. description: |- @@ -62,142 +52,176 @@ paths: operationId: storeInviteV2 security: - accessToken: [] - parameters: - - in: body - name: body - schema: - type: object - properties: - medium: - type: string - description: The literal string `email`. - example: "email" - address: - type: string - description: The email address of the invited user. - example: "foo@example.com" - room_id: - type: string - description: The Matrix room ID to which the user is invited - example: "!something:example.org" - sender: - type: string - description: The Matrix user ID of the inviting user - example: "@bob:example.com" - room_alias: - type: string - description: |- - The Matrix room alias for the room to which the user is - invited. This should be retrieved from the `m.room.canonical_alias` - state event. - example: "#somewhere:example.org" - room_avatar_url: - type: string - description: |- - The Content URI for the room to which the user is invited. This should - be retrieved from the `m.room.avatar` state event. - example: "mxc://example.org/s0meM3dia" - room_join_rules: - type: string - description: |- - The `join_rule` for the room to which the user is invited. This should - be retrieved from the `m.room.join_rules` state event. - example: "public" - room_name: - type: string - description: |- - The name of the room to which the user is invited. This should be retrieved - from the `m.room.name` state event. - example: "Bob's Emporium of Messages" - sender_display_name: - type: string - description: The display name of the user ID initiating the invite. - example: "Bob Smith" - sender_avatar_url: - type: string - description: The Content URI for the avatar of the user ID initiating the invite. - example: "mxc://example.org/an0th3rM3dia" - room_type: - type: string - description: |- - The `type` from the `m.room.create` event's `content`. If the create event doesn't - have a specified `type`, this field is not included. - example: "m.space" - required: ["medium", "address", "room_id", "sender"] + requestBody: + content: + application/json: + schema: + type: object + properties: + medium: + type: string + description: The literal string `email`. + example: email + address: + type: string + description: The email address of the invited user. + example: foo@example.com + room_id: + type: string + description: The Matrix room ID to which the user is invited + example: "!something:example.org" + sender: + type: string + description: The Matrix user ID of the inviting user + example: "@bob:example.com" + room_alias: + type: string + description: |- + The Matrix room alias for the room to which the user is + invited. This should be retrieved from the `m.room.canonical_alias` + state event. + example: "#somewhere:example.org" + room_avatar_url: + type: string + description: |- + The Content URI for the room to which the user is invited. This should + be retrieved from the `m.room.avatar` state event. + example: mxc://example.org/s0meM3dia + room_join_rules: + type: string + description: |- + The `join_rule` for the room to which the user is invited. This should + be retrieved from the `m.room.join_rules` state event. + example: public + room_name: + type: string + description: |- + The name of the room to which the user is invited. This should be retrieved + from the `m.room.name` state event. + example: Bob's Emporium of Messages + sender_display_name: + type: string + description: The display name of the user ID initiating the invite. + example: Bob Smith + sender_avatar_url: + type: string + description: The Content URI for the avatar of the user ID initiating the + invite. + example: mxc://example.org/an0th3rM3dia + room_type: + type: string + description: |- + The `type` from the `m.room.create` event's `content`. If the create event doesn't + have a specified `type`, this field is not included. + example: m.space + required: + - medium + - address + - room_id + - sender responses: - 200: + "200": description: The invitation was stored. - schema: - type: object - properties: - token: - type: string - description: | - The generated token. Must be a string consisting of the - characters `[0-9a-zA-Z.=_-]`. Its length must not exceed - 255 characters and it must not be empty. - public_keys: - type: array - description: | - A list of [server's long-term public key, generated ephemeral - public key]. - items: - type: object - title: PublicKey - properties: - public_key: - type: string - description: | - The public key, encoded using [unpadded Base64](/appendices/#unpadded-base64). - key_validity_url: - type: string - description: | - The URI of an endpoint where the validity of this key can be checked - by passing it as a `public_key` query parameter. See - [key management](/identity-service-api/#key-management). - required: ['public_key', 'key_validity_url'] - display_name: - type: string - description: The generated (redacted) display name. - required: ['token', 'public_keys', 'display_name'] - examples: - application/json: { - "token": "sometoken", - "public_keys": [ - { - "public_key": "serverPublicKeyBase64", - "key_validity_url": "https://example.com/_matrix/identity/v2/pubkey/isvalid" - }, - { - "public_key": "ephemeralPublicKeyBase64", - "key_validity_url": "https://example.com/_matrix/identity/v2/pubkey/ephemeral/isvalid" - } - ], - "display_name": "f...@b..." - } - 400: + content: + application/json: + schema: + type: object + properties: + token: + type: string + description: | + The generated token. Must be a string consisting of the + characters `[0-9a-zA-Z.=_-]`. Its length must not exceed + 255 characters and it must not be empty. + public_keys: + type: array + description: | + A list of [server's long-term public key, generated ephemeral + public key]. + items: + type: object + title: PublicKey + properties: + public_key: + type: string + description: | + The public key, encoded using [unpadded Base64](/appendices/#unpadded-base64). + key_validity_url: + type: string + description: | + The URI of an endpoint where the validity of this key can be checked + by passing it as a `public_key` query parameter. See + [key management](/identity-service-api/#key-management). + required: + - public_key + - key_validity_url + display_name: + type: string + description: The generated (redacted) display name. + required: + - token + - public_keys + - display_name + examples: + response: + value: { + "token": "sometoken", + "public_keys": [ + { + "public_key": "serverPublicKeyBase64", + "key_validity_url": "https://example.com/_matrix/identity/v2/pubkey/isvalid" + }, + { + "public_key": "ephemeralPublicKeyBase64", + "key_validity_url": "https://example.com/_matrix/identity/v2/pubkey/ephemeral/isvalid" + } + ], + "display_name": "f...@b..." + } + "400": description: | An error has occurred. If the 3pid is already bound to a Matrix user ID, the error code will be `M_THREEPID_IN_USE`. If the medium is unsupported, the error code will be `M_UNRECOGNIZED`. - examples: - application/json: { - "errcode": "M_THREEPID_IN_USE", - "error": "Binding already known", - "mxid": "@alice:example.com" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" - 403: + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_THREEPID_IN_USE", + "error": "Binding already known", + "mxid": "@alice:example.com" + } + "403": description: | The user must do something in order to use this endpoint. One example is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service). - examples: - application/json: { - "errcode": "M_TERMS_NOT_SIGNED", - "error": "Please accept our updated terms of service before continuing" - } - schema: - $ref: "../client-server/definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TERMS_NOT_SIGNED", + "error": "Please accept our updated terms of service before continuing" + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8090 + basePath: + default: /_matrix/identity/v2 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/identity/v2_terms.yaml b/data/api/identity/v2_terms.yaml index fcab28b7d..035688823 100644 --- a/data/api/identity/v2_terms.yaml +++ b/data/api/identity/v2_terms.yaml @@ -11,22 +11,12 @@ # 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 Identity Service Terms of Service API" - version: "2.0.0" -host: localhost:8090 -schemes: - - https -basePath: /_matrix/identity/v2 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Identity Service Terms of Service API + version: 2.0.0 paths: - "/terms": + /terms: get: summary: Gets the terms of service offered by the server. description: |- @@ -34,81 +24,84 @@ paths: to filter through the terms to determine which terms need acceptance from the user. Note that this endpoint does not require authentication. operationId: getTerms - parameters: [] responses: - 200: - description: |- - The terms of service offered by the server. - examples: - application/json: { - "policies": { - "terms_of_service": { - "version": "2.0", - "en": { - "name": "Terms of Service", - "url": "https://example.org/somewhere/terms-2.0-en.html" - }, - "fr": { - "name": "Conditions d'utilisation", - "url": "https://example.org/somewhere/terms-2.0-fr.html" - } - }, - "privacy_policy": { - "version": "1.2", - "en": { - "name": "Privacy Policy", - "url": "https://example.org/somewhere/privacy-1.2-en.html" - }, - "fr": { - "name": "Politique de confidentialité", - "url": "https://example.org/somewhere/privacy-1.2-fr.html" - } - } - } - } - schema: - type: object - properties: - policies: + "200": + description: The terms of service offered by the server. + content: + application/json: + schema: type: object - title: Policy Map - description: |- - The policies the server offers. Mapped from arbitrary ID (unused in - this version of the specification) to a Policy Object. - additionalProperties: - type: object - title: Policy Object - description: |- - The policy. Includes a map of language (ISO 639-2) to language-specific - policy information. - properties: - version: - type: string - description: |- - The version for the policy. There are no requirements on what this - might be and could be "alpha", semantically versioned, or arbitrary. - required: ['version'] - # TODO: TravisR - Make this render - additionalProperties: + properties: + policies: type: object - title: Internationalised Policy + title: Policy Map description: |- - The policy information for the specified language. - properties: - name: - type: string - description: The translated name of the policy. - url: - type: string - description: |- - The URL, which should include the policy ID, version, and language - in it, to be presented to the user as the policy. URLs should have - all three criteria to avoid conflicts when the policy is updated - in the future: for example, if this was "https://example.org/terms.html" - then the server would be unable to update it because the client would - have already added that URL to the `m.accepted_terms` collection. - required: ['name', 'url'] - required: ['policies'] + The policies the server offers. Mapped from arbitrary ID (unused in + this version of the specification) to a Policy Object. + additionalProperties: + type: object + title: Policy Object + description: |- + The policy. Includes a map of language (ISO 639-2) to language-specific + policy information. + properties: + version: + type: string + description: |- + The version for the policy. There are no requirements on what this + might be and could be "alpha", semantically versioned, or arbitrary. + required: + - version + additionalProperties: + type: object + title: Internationalised Policy + description: The policy information for the specified language. + properties: + name: + type: string + description: The translated name of the policy. + url: + type: string + description: |- + The URL, which should include the policy ID, version, and language + in it, to be presented to the user as the policy. URLs should have + all three criteria to avoid conflicts when the policy is updated + in the future: for example, if this was "https://example.org/terms.html" + then the server would be unable to update it because the client would + have already added that URL to the `m.accepted_terms` collection. + required: + - name + - url + required: + - policies + examples: + response: + value: { + "policies": { + "terms_of_service": { + "version": "2.0", + "en": { + "name": "Terms of Service", + "url": "https://example.org/somewhere/terms-2.0-en.html" + }, + "fr": { + "name": "Conditions d'utilisation", + "url": "https://example.org/somewhere/terms-2.0-fr.html" + } + }, + "privacy_policy": { + "version": "1.2", + "en": { + "name": "Privacy Policy", + "url": "https://example.org/somewhere/privacy-1.2-en.html" + }, + "fr": { + "name": "Politique de confidentialité", + "url": "https://example.org/somewhere/privacy-1.2-fr.html" + } + } + } + } post: summary: Indicates acceptance of terms to the server. description: |- @@ -126,24 +119,43 @@ paths: operationId: agreeToTerms security: - accessToken: [] - parameters: - - in: body - name: body - schema: - type: object - properties: - user_accepts: - type: array - items: - type: string - description: The URLs the user is accepting in this request. - example: "https://example.org/somewhere/terms-2.0-en.html" - required: ['user_accepts'] + requestBody: + content: + application/json: + schema: + type: object + properties: + user_accepts: + type: array + items: + type: string + description: The URLs the user is accepting in this request. + example: https://example.org/somewhere/terms-2.0-en.html + required: + - user_accepts responses: - 200: - description: |- - The server has considered the user as having accepted the provided URLs. - examples: - application/json: {} - schema: - type: object + "200": + description: The server has considered the user as having accepted the provided + URLs. + content: + application/json: + schema: + type: object + examples: + response: + value: {} +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8090 + basePath: + default: /_matrix/identity/v2 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/identity/versions.yaml b/data/api/identity/versions.yaml index ff821e22f..5338b6f35 100644 --- a/data/api/identity/versions.yaml +++ b/data/api/identity/versions.yaml @@ -11,18 +11,12 @@ # 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 Identity Service Versions API" - version: "1.0.0" -host: localhost:8090 -schemes: - - https -basePath: /_matrix/identity -produces: - - application/json + title: Matrix Identity Service Versions API + version: 1.0.0 paths: - "/versions": + /versions: get: x-addedInMatrixVersion: "1.1" summary: Gets the versions of the specification supported by the server. @@ -36,19 +30,39 @@ paths: All supported versions, including patch versions, are reported by the server. operationId: getVersions responses: - 200: + "200": description: The versions supported by the server. - examples: - application/json: { - "versions": ["r0.2.0", "r0.2.1", "v1.1"] - } - schema: - type: object - properties: - versions: - type: array - description: The supported versions. - items: - type: string - description: The supported versions. - required: ['versions'] + content: + application/json: + schema: + type: object + properties: + versions: + type: array + description: The supported versions. + items: + type: string + description: The supported versions. + required: + - versions + examples: + response: + value: { + "versions": [ + "r0.2.0", + "r0.2.1", + "v1.1" + ] + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8090 + basePath: + default: /_matrix/identity diff --git a/data/api/push-gateway/push_notifier.yaml b/data/api/push-gateway/push_notifier.yaml index 96d61bf09..c64011d25 100644 --- a/data/api/push-gateway/push_notifier.yaml +++ b/data/api/push-gateway/push_notifier.yaml @@ -12,21 +12,12 @@ # 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 Push Notification API" - version: "1.0.0" -host: localhost:8008 -schemes: - - https - - http -basePath: /_matrix/push/v1 -consumes: - - application/json -produces: - - application/json + title: Matrix Push Notification API + version: 1.0.0 paths: - "/notify": + /notify: post: summary: Notify a push gateway about an event. description: |- @@ -48,182 +39,203 @@ paths: This means that the HTTP path may be different depending on the push gateway. operationId: notify - parameters: - - in: body - name: notification - description: Information about the push notification. - required: true - schema: - type: object - example: { - "notification": { - "event_id": "$3957tyerfgewrf384", - "room_id": "!slw48wfj34rtnrf:example.com", - "type": "m.room.message", - "sender": "@exampleuser:matrix.org", - "sender_display_name": "Major Tom", - "room_name": "Mission Control", - "room_alias": "#exampleroom:matrix.org", - "prio": "high", - "content": { - "msgtype": "m.text", - "body": "I'm floating in a most peculiar way." - }, - "counts": { - "unread" : 2, - "missed_calls": 1 - }, - "devices": [ - { - "app_id": "org.matrix.matrixConsole.ios", - "pushkey": "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/", - "pushkey_ts": 12345678, - "data" : {}, - "tweaks": { - "sound": "bing" + requestBody: + content: + application/json: + schema: + type: object + example: { + "notification": { + "event_id": "$3957tyerfgewrf384", + "room_id": "!slw48wfj34rtnrf:example.com", + "type": "m.room.message", + "sender": "@exampleuser:matrix.org", + "sender_display_name": "Major Tom", + "room_name": "Mission Control", + "room_alias": "#exampleroom:matrix.org", + "prio": "high", + "content": { + "msgtype": "m.text", + "body": "I'm floating in a most peculiar way." + }, + "counts": { + "unread": 2, + "missed_calls": 1 + }, + "devices": [ + { + "app_id": "org.matrix.matrixConsole.ios", + "pushkey": "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/", + "pushkey_ts": 12345678, + "data": {}, + "tweaks": { + "sound": "bing" + } } - } - ] + ] + } } - } - required: ["notification"] - properties: - notification: - type: object - title: Notification - description: Information about the push notification - required: ["devices"] - properties: - event_id: - type: string - description: |- - The Matrix event ID of the event being notified about. - This is required if the notification is about a - particular Matrix event. It may be omitted for notifications - that only contain updated badge counts. This ID can and - should be used to detect duplicate notification requests. - room_id: - type: string - description: |- - The ID of the room in which this event occurred. - Required if the notification relates to a specific - Matrix event. - type: - type: string - description: |- - The type of the event as in the event's `type` field. - sender: - type: string - description: |- - The sender of the event as in the corresponding event field. - sender_display_name: - type: string - description: |- - The current display name of the sender in the room in which - the event occurred. - room_name: - type: string - description: The name of the room in which the event occurred. - room_alias: - type: string - description: An alias to display for the room in which the event occurred. - user_is_target: - type: boolean - description: |- - This is true if the user receiving the notification is the - subject of a member event (i.e. the `state_key` of the - member event is equal to the user's Matrix ID). - prio: - type: string - enum: ["high", "low"] - description: |- - The priority of the notification. If omitted, `high` is - assumed. This may be used by push gateways to deliver less - time-sensitive notifications in a way that will preserve - battery power on mobile devices. - content: - type: object - title: EventContent - description: |- - The `content` field from the event, if present. The pusher - may omit this if the event had no content or for any other - reason. - counts: - type: object - title: Counts - description: |- - This is a dictionary of the current number of unacknowledged - communications for the recipient user. Counts whose value is - zero should be omitted. - properties: - unread: - type: integer - description: |- - The number of unread messages a user has across all of the - rooms they are a member of. - missed_calls: - type: integer - description: |- - The number of unacknowledged missed calls a user has - across all rooms of which they are a member. - devices: - type: array - title: Devices - description: |- - This is an array of devices that the notification should be sent to. - items: + required: + - notification + properties: + notification: + type: object + title: Notification + description: Information about the push notification + required: + - devices + properties: + event_id: + type: string + description: |- + The Matrix event ID of the event being notified about. + This is required if the notification is about a + particular Matrix event. It may be omitted for notifications + that only contain updated badge counts. This ID can and + should be used to detect duplicate notification requests. + room_id: + type: string + description: |- + The ID of the room in which this event occurred. + Required if the notification relates to a specific + Matrix event. + type: + type: string + description: The type of the event as in the event's `type` field. + sender: + type: string + description: The sender of the event as in the corresponding event field. + sender_display_name: + type: string + description: |- + The current display name of the sender in the room in which + the event occurred. + room_name: + type: string + description: The name of the room in which the event occurred. + room_alias: + type: string + description: An alias to display for the room in which the event occurred. + user_is_target: + type: boolean + description: |- + This is true if the user receiving the notification is the + subject of a member event (i.e. the `state_key` of the + member event is equal to the user's Matrix ID). + prio: + type: string + enum: + - high + - low + description: |- + The priority of the notification. If omitted, `high` is + assumed. This may be used by push gateways to deliver less + time-sensitive notifications in a way that will preserve + battery power on mobile devices. + content: + type: object + title: EventContent + description: |- + The `content` field from the event, if present. The pusher + may omit this if the event had no content or for any other + reason. + counts: type: object - title: Device + title: Counts + description: |- + This is a dictionary of the current number of unacknowledged + communications for the recipient user. Counts whose value is + zero should be omitted. properties: - app_id: - type: string - description: |- - The `app_id` given when the pusher was created. - pushkey: - type: string - description: The `pushkey` given when the pusher was created. - pushkey_ts: + unread: type: integer - format: int64 - description: |- - The unix timestamp (in seconds) when the - pushkey was last updated. - data: - type: object - title: PusherData description: |- - A dictionary of additional pusher-specific data. For - 'http' pushers, this is the data dictionary passed in at - pusher creation minus the `url` key. - tweaks: - type: object - title: Tweaks + The number of unread messages a user has across all of the + rooms they are a member of. + missed_calls: + type: integer description: |- - A dictionary of customisations made to the way this - notification is to be presented. These are added by push rules. - required: ['app_id', 'pushkey'] + The number of unacknowledged missed calls a user has + across all rooms of which they are a member. + devices: + type: array + title: Devices + description: This is an array of devices that the notification should be sent + to. + items: + type: object + title: Device + properties: + app_id: + type: string + description: The `app_id` given when the pusher was created. + pushkey: + type: string + description: The `pushkey` given when the pusher was created. + pushkey_ts: + type: integer + format: int64 + description: |- + The unix timestamp (in seconds) when the + pushkey was last updated. + data: + type: object + title: PusherData + description: |- + A dictionary of additional pusher-specific data. For + 'http' pushers, this is the data dictionary passed in at + pusher creation minus the `url` key. + tweaks: + type: object + title: Tweaks + description: |- + A dictionary of customisations made to the way this + notification is to be presented. These are added by push rules. + required: + - app_id + - pushkey + description: Information about the push notification. + required: true responses: - 200: + "200": description: A list of rejected push keys. - examples: - application/json: { - "rejected": [ "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/" ] - } - schema: - type: object # empty json object - properties: - rejected: - type: array - description: |- - A list of all pushkeys given in the notification request that - are not valid. These could have been rejected by an upstream - gateway because they have expired or have never been valid. - Homeservers must cease sending notification requests for these - pushkeys and remove the associated pushers. It may not - necessarily be the notification in the request that failed: - it could be that a previous notification to the same pushkey - failed. May be empty. - items: - type: string - description: A pushkey that has been rejected. - required: ['rejected'] + content: + application/json: + schema: + type: object + properties: + rejected: + type: array + description: |- + A list of all pushkeys given in the notification request that + are not valid. These could have been rejected by an upstream + gateway because they have expired or have never been valid. + Homeservers must cease sending notification requests for these + pushkeys and remove the associated pushers. It may not + necessarily be the notification in the request that failed: + it could be that a previous notification to the same pushkey + failed. May be empty. + items: + type: string + description: A pushkey that has been rejected. + required: + - rejected + examples: + response: + value: { + "rejected": [ + "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/" + ] + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/push/v1 diff --git a/data/api/server-server/backfill.yaml b/data/api/server-server/backfill.yaml index 6adeb26c9..9d82edc72 100644 --- a/data/api/server-server/backfill.yaml +++ b/data/api/server-server/backfill.yaml @@ -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 Federation Events API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation Events API + version: 1.0.0 paths: "/backfill/{roomId}": get: @@ -40,26 +29,32 @@ paths: parameters: - in: path name: roomId - type: string description: The room ID to backfill. required: true - x-example: "!SomeRoom:matrix.org" + example: "!SomeRoom:matrix.org" + schema: + type: string - in: query name: v - type: array - items: - type: string description: The event IDs to backfill from. required: true - x-example: ["$abc123:matrix.org"] + example: + - $abc123:matrix.org + style: form + explode: false + schema: + type: array + items: + type: string - in: query name: limit - type: integer description: The maximum number of PDUs to retrieve, including the given events. required: true - x-example: 2 + example: 2 + schema: + type: integer responses: - 200: + "200": description: |- A transaction containing the PDUs that preceded the given event(s), including the given event(s), up to the given limit. @@ -71,8 +66,10 @@ paths: Due to historical reasons, it is possible that events which were previously accepted would now be rejected by these limitations. The events should be rejected per usual by the `/send`, `/get_missing_events`, and remaining endpoints. - schema: - $ref: "definitions/unlimited_pdu_transaction.yaml" + content: + application/json: + schema: + $ref: definitions/unlimited_pdu_transaction.yaml "/get_missing_events/{roomId}": post: summary: Retrieves events that the sender is missing @@ -86,58 +83,85 @@ paths: parameters: - in: path name: roomId - type: string description: The room ID to search in. required: true - x-example: "!SomeRoom:matrix.org" - - in: body - name: body + example: "!SomeRoom:matrix.org" schema: - type: object - properties: - limit: - type: integer - description: The maximum number of events to retrieve. Defaults to 10. - example: 10 - min_depth: - type: integer - description: The minimum depth of events to retrieve. Defaults to 0. - example: 0 - earliest_events: - type: array - description: |- - The latest event IDs that the sender already has. These are skipped when retrieving - the previous events of `latest_events`. - items: - type: string - example: ["$missing_event:example.org"] - latest_events: - type: array - description: The event IDs to retrieve the previous events for. - items: - type: string - example: ["$event_that_has_the_missing_event_as_a_previous_event:example.org"] - required: ['earliest_events', 'latest_events'] + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + limit: + type: integer + description: The maximum number of events to retrieve. Defaults to 10. + example: 10 + min_depth: + type: integer + description: The minimum depth of events to retrieve. Defaults to 0. + example: 0 + earliest_events: + type: array + description: |- + The latest event IDs that the sender already has. These are skipped when retrieving + the previous events of `latest_events`. + items: + type: string + example: + - $missing_event:example.org + latest_events: + type: array + description: The event IDs to retrieve the previous events for. + items: + type: string + example: + - $event_that_has_the_missing_event_as_a_previous_event:example.org + required: + - earliest_events + - latest_events responses: - 200: + "200": description: |- The previous events for `latest_events`, excluding any `earliest_events`, up to the provided `limit`. - schema: - type: object - properties: - events: - type: array - description: |- - The missing events. The event format varies depending on the room version - check - the [room version specification](/rooms) for precise event formats. - items: - type: object - title: PDU - required: ['events'] - examples: - application/json: { - "events": [ - {"$ref": "examples/minimal_pdu.json"} - ] - } + content: + application/json: + schema: + type: object + properties: + events: + type: array + description: |- + The missing events. The event format varies depending on the room version - check + the [room version specification](/rooms) for precise event formats. + items: + type: object + title: PDU + required: + - events + examples: + response: + value: { + "events": [ + { + "$ref": "examples/minimal_pdu.json" + } + ] + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/event_auth.yaml b/data/api/server-server/event_auth.yaml index ae4db262b..99d2b3acb 100644 --- a/data/api/server-server/event_auth.yaml +++ b/data/api/server-server/event_auth.yaml @@ -11,60 +11,68 @@ # 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 Federation Event Authorization API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation Event Authorization API + version: 1.0.0 paths: "/event_auth/{roomId}/{eventId}": get: summary: Get the auth chain for a given event - description: |- - Retrieves the complete auth chain for a given event. + description: Retrieves the complete auth chain for a given event. operationId: getEventAuth security: - signedRequest: [] parameters: - in: path name: roomId - type: string description: The room ID to get the auth chain for. required: true - x-example: "!abc123:matrix.org" + example: "!abc123:matrix.org" + schema: + type: string - in: path name: eventId - type: string description: The event ID to get the auth chain of. required: true - x-example: "$helloworld:example.org" + example: $helloworld:example.org + schema: + type: string responses: - 200: + "200": description: The auth chain for the event. - schema: - type: object - properties: - auth_chain: - type: array - description: |- - The [PDUs](/server-server-api/#pdus) forming the auth chain - of the given event. The event format varies depending on the - room version - check the [room version specification](/rooms) - for precise event formats. - items: - type: object - title: PDU - properties: {} - example: - $ref: "examples/minimal_pdu.json" - required: ['auth_chain'] + content: + application/json: + schema: + type: object + properties: + auth_chain: + type: array + description: |- + The [PDUs](/server-server-api/#pdus) forming the auth chain + of the given event. The event format varies depending on the + room version - check the [room version specification](/rooms) + for precise event formats. + items: + type: object + title: PDU + properties: {} + example: + $ref: examples/minimal_pdu.json + required: + - auth_chain +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/events.yaml b/data/api/server-server/events.yaml index 427978fbb..5ad87f5fe 100644 --- a/data/api/server-server/events.yaml +++ b/data/api/server-server/events.yaml @@ -11,84 +11,80 @@ # 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 Federation Events API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation Events API + version: 1.0.0 paths: "/state/{roomId}": get: summary: Get all the state of a given room - description: |- - Retrieves a snapshot of a room's state at a given event. + description: Retrieves a snapshot of a room's state at a given event. operationId: getRoomState security: - signedRequest: [] parameters: - in: path name: roomId - type: string description: The room ID to get state for. required: true - x-example: "!abc123:matrix.org" + example: "!abc123:matrix.org" + schema: + type: string - in: query name: event_id - type: string description: An event ID in the room to retrieve the state at. required: true - x-example: "$helloworld:matrix.org" + example: $helloworld:matrix.org + schema: + type: string responses: - 200: + "200": description: |- The fully resolved state for the room, prior to considering any state changes induced by the requested event. Includes the authorization chain for the events. - schema: - type: object - properties: - auth_chain: - type: array - description: |- - The full set of authorization events that make up the state - of the room, and their authorization events, recursively. Note that - events have a different format depending on the room version - - check the [room version specification](/rooms) for precise event formats. - items: - type: object - title: PDU - description: |- - The [PDUs](/server-server-api/#pdus) contained in the auth chain. The event format - varies depending on the room version - check the [room version specification](/rooms) - for precise event formats. - properties: {} - example: - $ref: "examples/minimal_pdu.json" - pdus: - type: array - description: |- - The fully resolved state of the room at the given event. Note that - events have a different format depending on the room version - - check the [room version specification](/rooms) for precise event formats. - items: - type: object - title: PDU - description: |- - The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format - varies depending on the room version - check the [room version specification](/rooms) - for precise event formats. - properties: {} - example: - $ref: "examples/minimal_pdu.json" - required: ['auth_chain', 'pdus'] + content: + application/json: + schema: + type: object + properties: + auth_chain: + type: array + description: |- + The full set of authorization events that make up the state + of the room, and their authorization events, recursively. Note that + events have a different format depending on the room version - + check the [room version specification](/rooms) for precise event formats. + items: + type: object + title: PDU + description: |- + The [PDUs](/server-server-api/#pdus) contained in the auth chain. The event format + varies depending on the room version - check the [room version specification](/rooms) + for precise event formats. + properties: {} + example: + $ref: examples/minimal_pdu.json + pdus: + type: array + description: |- + The fully resolved state of the room at the given event. Note that + events have a different format depending on the room version - + check the [room version specification](/rooms) for precise event formats. + items: + type: object + title: PDU + description: |- + The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format + varies depending on the room version - check the [room version specification](/rooms) + for precise event formats. + properties: {} + example: + $ref: examples/minimal_pdu.json + required: + - auth_chain + - pdus "/state_ids/{roomId}": get: summary: Get all the state event IDs of a given room @@ -102,61 +98,70 @@ paths: parameters: - in: path name: roomId - type: string description: The room ID to get state for. required: true - x-example: "!abc123:matrix.org" + example: "!abc123:matrix.org" + schema: + type: string - in: query name: event_id - type: string description: An event ID in the room to retrieve the state at. required: true - x-example: "$helloworld:matrix.org" + example: $helloworld:matrix.org + schema: + type: string responses: - 200: + "200": description: |- The fully resolved state for the room, prior to considering any state changes induced by the requested event. Includes the authorization chain for the events. - schema: - type: object - properties: - auth_chain_ids: - type: array - description: |- - The full set of authorization events that make up the state - of the room, and their authorization events, recursively. - items: - type: string - example: ["$an_event:example.org"] - pdu_ids: - type: array - description: |- - The fully resolved state of the room at the given event. - items: - type: string - example: ["$an_event:example.org"] - required: ['auth_chain_ids', 'pdu_ids'] + content: + application/json: + schema: + type: object + properties: + auth_chain_ids: + type: array + description: |- + The full set of authorization events that make up the state + of the room, and their authorization events, recursively. + items: + type: string + example: + - $an_event:example.org + pdu_ids: + type: array + description: The fully resolved state of the room at the given event. + items: + type: string + example: + - $an_event:example.org + required: + - auth_chain_ids + - pdu_ids "/event/{eventId}": get: summary: Get a single event - description: |- - Retrieves a single event. + description: Retrieves a single event. operationId: getEvent security: - signedRequest: [] parameters: - in: path name: eventId - type: string description: The event ID to get. required: true - x-example: "$abc123:matrix.org" + example: $abc123:matrix.org + schema: + type: string responses: - 200: + "200": description: A transaction containing a single PDU which is the event requested. - schema: - $ref: "definitions/single_pdu_transaction.yaml" + content: + application/json: + schema: + $ref: definitions/single_pdu_transaction.yaml "/timestamp_to_event/{roomId}": get: summary: Get the closest event ID to the given timestamp @@ -191,55 +196,79 @@ paths: - accessToken: [] parameters: - in: path - type: string name: roomId description: The ID of the room to search required: true - x-example: "!636q39766251:matrix.org" + example: "!636q39766251:matrix.org" + schema: + type: string - in: query - type: integer name: ts description: |- The timestamp to search from, as given in milliseconds since the Unix epoch. required: true - x-example: 1432684800000 + example: 1432684800000 + schema: + type: integer - in: query - type: string - enum: [f, b] name: dir - description: |- - The direction in which to search. `f` for forwards, `b` for backwards. + description: The direction in which to search. `f` for forwards, `b` for + backwards. required: true - x-example: f - responses: - 200: - description: |- - An event was found matching the search parameters. - schema: - type: object - properties: - event_id: - type: string - description: |- - The ID of the event found - origin_server_ts: - type: integer - description: |- - The event's timestamp, in milliseconds since the Unix epoch. - required: ['event_id', 'origin_server_ts'] - examples: - application/json: { - "event_id": "$143273582443PhrSn:example.org", - "origin_server_ts": 1432735824653 - } - 404: - description: |- - No event was found. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Unable to find event from 1432684800000 in forward direction" - } + example: f schema: - "$ref": "../client-server/definitions/errors/error.yaml" + type: string + enum: + - f + - b + responses: + "200": + description: An event was found matching the search parameters. + content: + application/json: + schema: + type: object + properties: + event_id: + type: string + description: The ID of the event found + origin_server_ts: + type: integer + description: The event's timestamp, in milliseconds since the Unix epoch. + required: + - event_id + - origin_server_ts + examples: + response: + value: { + "event_id": "$143273582443PhrSn:example.org", + "origin_server_ts": 1432735824653 + } + "404": + description: No event was found. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Unable to find event from 1432684800000 in forward direction" + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/invites-v1.yaml b/data/api/server-server/invites-v1.yaml index ee439aa21..78a24b498 100644 --- a/data/api/server-server/invites-v1.yaml +++ b/data/api/server-server/invites-v1.yaml @@ -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 Federation Invite User To Room API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation Invite User To Room API + version: 1.0.0 paths: "/invite/{roomId}/{eventId}": put: @@ -49,134 +38,144 @@ paths: parameters: - in: path name: roomId - type: string description: The room ID that the user is being invited to. required: true - x-example: "!abc123:matrix.org" + example: "!abc123:matrix.org" + schema: + type: string - in: path name: eventId - type: string description: The event ID for the invite event, generated by the inviting server. required: true - x-example: "$abc123:example.org" - - in: body - name: body - type: object - required: true + example: $abc123:example.org schema: - allOf: - - $ref: "definitions/invite_event.yaml" - - type: object - properties: - unsigned: - type: object - title: UnsignedData - description: |- - Information included alongside the event that is not signed. May include more - than what is listed here. - properties: - invite_room_state: - type: array - description: |- - An optional list of [stripped state events](/client-server-api/#stripped-state) - to help the receiver of the invite identify the room. - items: - $ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml" - example: - $ref: "../../event-schemas/examples/invite_room_state.json" - example: { - "room_id": "!somewhere:example.org", - "type": "m.room.member", - "state_key": "@joe:elsewhere.com", - "origin": "example.org", - "origin_server_ts": 1549041175876, - "sender": "@someone:example.org", - "content": { - "membership": "invite" - }, - "signatures": { - "example.com": { - "ed25519:key_version": "SomeSignatureHere" - }, - } - } + type: string + requestBody: + content: + application/json: + schema: + allOf: + - $ref: definitions/invite_event.yaml + - type: object + properties: + unsigned: + type: object + title: UnsignedData + description: |- + Information included alongside the event that is not signed. May include more + than what is listed here. + properties: + invite_room_state: + type: array + description: |- + An optional list of [stripped state events](/client-server-api/#stripped-state) + to help the receiver of the invite identify the room. + items: + $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml + example: + $ref: ../../event-schemas/examples/invite_room_state.json + type: object + required: true responses: - 200: + "200": description: |- The event with the invited server's signature added. All other fields of the events should remain untouched. Note that events have a different format depending on the room version - check the [room version specification](/rooms) for precise event formats. - schema: - type: array - minItems: 2 - maxItems: 2 - items: - - type: integer - description: The value `200`. - example: 200 - - type: object - description: An object containing the signed invite event. - title: Event Container - properties: - event: - $ref: "definitions/invite_event.yaml" - required: ['event'] - examples: - application/json: [ - 200, - { - "event": { - "room_id": "!somewhere:example.org", - "type": "m.room.member", - "state_key": "@someone:example.org", - "origin": "example.org", - "origin_server_ts": 1549041175876, - "sender": "@someone:example.org", - "unsigned": { - "invite_room_state": [ - { - "type": "m.room.name", - "sender": "@bob:example.org", - "state_key": "", + content: + application/json: + schema: + type: array + minItems: 2 + maxItems: 2 + items: + anyOf: + - type: integer + description: The value `200`. + example: 200 + - type: object + description: An object containing the signed invite event. + title: Event Container + properties: + event: + $ref: definitions/invite_event.yaml + required: + - event + examples: + response: + value: [ + 200, + { + "event": { + "room_id": "!somewhere:example.org", + "type": "m.room.member", + "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "unsigned": { + "invite_room_state": [ + { + "type": "m.room.name", + "sender": "@bob:example.org", + "state_key": "", + "content": { + "name": "Example Room" + } + }, + { + "type": "m.room.join_rules", + "sender": "@bob:example.org", + "state_key": "", + "content": { + "join_rule": "invite" + } + } + ] + }, "content": { - "name": "Example Room" - } - }, - { - "type": "m.room.join_rules", - "sender": "@bob:example.org", - "state_key": "", - "content": { - "join_rule": "invite" + "membership": "invite" + }, + "signatures": { + "example.com": { + "ed25519:key_version": "SomeSignatureHere" + }, + "elsewhere.com": { + "ed25519:k3y_versi0n": "SomeOtherSignatureHere" + } } } - ] - }, - "content": { - "membership": "invite" - }, - "signatures": { - "example.com": { - "ed25519:key_version": "SomeSignatureHere" - }, - "elsewhere.com": { - "ed25519:k3y_versi0n": "SomeOtherSignatureHere" } - } - } - } - ] - 403: + ] + "403": description: |- The invite is not allowed. This could be for a number of reasons, including: * The sender is not allowed to send invites to the target user/homeserver. * The homeserver does not permit anyone to invite its users. * The homeserver refuses to participate in the room. - schema: - $ref: "../client-server/definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "User cannot invite the target user." - } + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "User cannot invite the target user." + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/invites-v2.yaml b/data/api/server-server/invites-v2.yaml index afb8a5711..5006a1882 100644 --- a/data/api/server-server/invites-v2.yaml +++ b/data/api/server-server/invites-v2.yaml @@ -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 Federation Invite User To Room API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v2 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation Invite User To Room API + version: 1.0.0 paths: "/invite/{roomId}/{eventId}": put: @@ -53,129 +42,104 @@ paths: parameters: - in: path name: roomId - type: string description: The room ID that the user is being invited to. required: true - x-example: "!abc123:matrix.org" + example: "!abc123:matrix.org" + schema: + type: string - in: path name: eventId - type: string description: The event ID for the invite event, generated by the inviting server. required: true - x-example: "$abc123:example.org" - - in: body - name: body - type: object - required: true + example: $abc123:example.org schema: - type: object - properties: - room_version: - type: string - description: The version of the room where the user is being invited to. - example: "2" - event: - $ref: "definitions/invite_event.yaml" - invite_room_state: - type: array - description: |- - An optional list of [stripped state events](/client-server-api/#stripped-state) - to help the receiver of the invite identify the room. - items: - $ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml" - example: - $ref: "../../event-schemas/examples/invite_room_state.json" - required: ['room_version', 'event'] - example: { - "room_version": "2", - "event": { - "room_id": "!somewhere:example.org", - "type": "m.room.member", - "state_key": "@joe:elsewhere.com", - "origin": "example.org", - "origin_server_ts": 1549041175876, - "sender": "@someone:example.org", - "content": { - "membership": "invite" - }, - "signatures": { - "example.com": { - "ed25519:key_version": "SomeSignatureHere" - }, - } - } - } + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + room_version: + type: string + description: The version of the room where the user is being invited to. + example: "2" + event: + $ref: definitions/invite_event.yaml + invite_room_state: + type: array + description: |- + An optional list of [stripped state events](/client-server-api/#stripped-state) + to help the receiver of the invite identify the room. + items: + $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml + example: + $ref: ../../event-schemas/examples/invite_room_state.json + required: + - room_version + - event + required: true responses: - 200: + "200": description: |- The event with the invited server's signature added. All other fields of the events should remain untouched. Note that events have a different format depending on the room version - check the [room version specification](/rooms) for precise event formats. - schema: - type: object - description: An object containing the signed invite event. - title: Event Container - properties: - event: - $ref: "definitions/invite_event.yaml" - required: ['event'] - examples: - application/json: { - "event": { - "room_id": "!somewhere:example.org", - "type": "m.room.member", - "state_key": "@someone:example.org", - "origin": "example.org", - "origin_server_ts": 1549041175876, - "sender": "@someone:example.org", - "unsigned": { - "invite_room_state": [ - { - "type": "m.room.name", - "sender": "@bob:example.org", - "state_key": "", - "content": { - "name": "Example Room" - } - }, - { - "type": "m.room.join_rules", - "sender": "@bob:example.org", - "state_key": "", + content: + application/json: + schema: + type: object + description: An object containing the signed invite event. + title: Event Container + properties: + event: + $ref: definitions/invite_event.yaml + required: + - event + examples: + response: + value: { + "event": { + "room_id": "!somewhere:example.org", + "type": "m.room.member", + "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "unsigned": { + "invite_room_state": [ + { + "type": "m.room.name", + "sender": "@bob:example.org", + "state_key": "", + "content": { + "name": "Example Room" + } + }, + { + "type": "m.room.join_rules", + "sender": "@bob:example.org", + "state_key": "", + "content": { + "join_rule": "invite" + } + } + ] + }, "content": { - "join_rule": "invite" + "membership": "invite" + }, + "signatures": { + "example.com": { + "ed25519:key_version": "SomeSignatureHere" + }, + "elsewhere.com": { + "ed25519:k3y_versi0n": "SomeOtherSignatureHere" + } } } - ] - }, - "content": { - "membership": "invite" - }, - "signatures": { - "example.com": { - "ed25519:key_version": "SomeSignatureHere" - }, - "elsewhere.com": { - "ed25519:k3y_versi0n": "SomeOtherSignatureHere" } - } - } - } - 403: - description: |- - The invite is not allowed. This could be for a number of reasons, including: - - * The sender is not allowed to send invites to the target user/homeserver. - * The homeserver does not permit anyone to invite its users. - * The homeserver refuses to participate in the room. - schema: - $ref: "../client-server/definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "User cannot invite the target user." - } - 400: + "400": description: |- The request is invalid or the room the server is attempting to join has a version that is not listed in the `ver` @@ -183,19 +147,54 @@ paths: The error should be passed through to clients so that they may give better feedback to users. - schema: - allOf: - - $ref: "../client-server/definitions/errors/error.yaml" - - type: object - properties: - room_version: - type: string - description: |- - The version of the room. Required if the `errcode` - is `M_INCOMPATIBLE_ROOM_VERSION`. - examples: - application/json: { - "errcode": "M_INCOMPATIBLE_ROOM_VERSION", - "error": "Your homeserver does not support the features required to join this room", - "room_version": "3" - } + content: + application/json: + schema: + allOf: + - $ref: ../client-server/definitions/errors/error.yaml + - type: object + properties: + room_version: + type: string + description: |- + The version of the room. Required if the `errcode` + is `M_INCOMPATIBLE_ROOM_VERSION`. + examples: + response: + value: { + "errcode": "M_INCOMPATIBLE_ROOM_VERSION", + "error": "Your homeserver does not support the features required to join this room", + "room_version": "3" + } + "403": + description: |- + The invite is not allowed. This could be for a number of reasons, including: + + * The sender is not allowed to send invites to the target user/homeserver. + * The homeserver does not permit anyone to invite its users. + * The homeserver refuses to participate in the room. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "User cannot invite the target user." + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v2 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/joins-v1.yaml b/data/api/server-server/joins-v1.yaml index edb987f2e..016381522 100644 --- a/data/api/server-server/joins-v1.yaml +++ b/data/api/server-server/joins-v1.yaml @@ -12,21 +12,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 Federation Join Room API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation Join Room API + version: 1.0.0 paths: "/make_join/{roomId}/{userId}": get: @@ -40,118 +29,130 @@ paths: parameters: - in: path name: roomId - type: string description: The room ID that is about to be joined. required: true - x-example: "!abc123:matrix.org" + example: "!abc123:matrix.org" + schema: + type: string - in: path name: userId - type: string description: The user ID the join event will be for. required: true - x-example: "@someone:example.org" - - in: query - type: array - items: + example: "@someone:example.org" + schema: type: string + - in: query name: ver description: |- The room versions the sending server has support for. Defaults to `[1]`. - x-example: ["1", "2"] + example: + - "1" + - "2" + style: form + explode: false + schema: + type: array + items: + type: string responses: - 200: + "200": description: |- A template to be used for the rest of the [Joining Rooms](/server-server-api/#joining-rooms) handshake. Note that events have a different format depending on the room version - check the [room version specification](/rooms) for precise event formats. **The response body here describes the common event fields in more detail and may be missing other required fields for a PDU.** - schema: - type: object - properties: - room_version: - type: string - description: |- - The version of the room where the server is trying to join. If not provided, - the room version is assumed to be either "1" or "2". - example: "2" - event: - description: |- - An unsigned template event. Note that events have a different format - depending on the room version - check the [room version specification](/rooms) - for precise event formats. + content: + application/json: + schema: type: object - title: Event Template properties: - sender: - type: string - description: The user ID of the joining member. - example: "@someone:example.org" - origin: - type: string - description: The name of the resident homeserver. - example: "matrix.org" - origin_server_ts: - type: integer - format: int64 - description: A timestamp added by the resident homeserver. - example: 1234567890 - type: - type: string - description: The value `m.room.member`. - example: "m.room.member" - state_key: + room_version: type: string - description: The user ID of the joining member. - example: "@someone:example.org" - content: + description: |- + The version of the room where the server is trying to join. If not provided, + the room version is assumed to be either "1" or "2". + example: "2" + event: + description: |- + An unsigned template event. Note that events have a different format + depending on the room version - check the [room version specification](/rooms) + for precise event formats. type: object - title: Membership Event Content - description: The content of the event. - example: {"membership": "join"} + title: Event Template properties: - membership: + sender: type: string - description: The value `join`. - example: "join" - join_authorised_via_users_server: + description: The user ID of the joining member. + example: "@someone:example.org" + origin: type: string - x-addedInMatrixVersion: "1.2" - description: |- - Required if the room is [restricted](/client-server-api/#restricted-rooms) - and is joining through one of the conditions available. If the - user is responding to an invite, this is not required. + description: The name of the resident homeserver. + example: matrix.org + origin_server_ts: + type: integer + format: int64 + description: A timestamp added by the resident homeserver. + example: 1234567890 + type: + type: string + description: The value `m.room.member`. + example: m.room.member + state_key: + type: string + description: The user ID of the joining member. + example: "@someone:example.org" + content: + type: object + title: Membership Event Content + description: The content of the event. + example: + membership: join + properties: + membership: + type: string + description: The value `join`. + example: join + join_authorised_via_users_server: + type: string + x-addedInMatrixVersion: "1.2" + description: |- + Required if the room is [restricted](/client-server-api/#restricted-rooms) + and is joining through one of the conditions available. If the + user is responding to an invite, this is not required. - An arbitrary user ID belonging to the resident server in - the room being joined that is able to issue invites to other - users. This is used in later validation of the auth rules for - the `m.room.member` event. - required: ['membership'] - required: - - state_key - - origin - - origin_server_ts - - type - - content - - sender - examples: - application/json: { - "room_version": "2", - "event": { - "room_id": "!somewhere:example.org", - "type": "m.room.member", - "state_key": "@someone:example.org", - "origin": "example.org", - "origin_server_ts": 1549041175876, - "sender": "@someone:example.org", - "content": { - "membership": "join", - "join_authorised_via_users_server": "@anyone:resident.example.org" - } - } - } - 400: + An arbitrary user ID belonging to the resident server in + the room being joined that is able to issue invites to other + users. This is used in later validation of the auth rules for + the `m.room.member` event. + required: + - membership + required: + - state_key + - origin + - origin_server_ts + - type + - content + - sender + examples: + response: + value: { + "room_version": "2", + "event": { + "room_id": "!somewhere:example.org", + "type": "m.room.member", + "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "join", + "join_authorised_via_users_server": "@anyone:resident.example.org" + } + } + } + "400": description: |- The request is invalid, the room the server is attempting to join has a version that is not listed in the `ver` @@ -177,45 +178,53 @@ paths: resident server would be unable to meet the auth rules governing `join_authorised_via_users_server` on the resulting `m.room.member` event. - schema: - allOf: - - $ref: "../client-server/definitions/errors/error.yaml" - - type: object - properties: - room_version: - type: string - description: |- - The version of the room. Required if the `errcode` - is `M_INCOMPATIBLE_ROOM_VERSION`. - examples: - application/json: { - "errcode": "M_INCOMPATIBLE_ROOM_VERSION", - "error": "Your homeserver does not support the features required to join this room", - "room_version": "3" - } - 403: - schema: - $ref: "../client-server/definitions/errors/error.yaml" + content: + application/json: + schema: + allOf: + - $ref: ../client-server/definitions/errors/error.yaml + - type: object + properties: + room_version: + type: string + description: |- + The version of the room. Required if the `errcode` + is `M_INCOMPATIBLE_ROOM_VERSION`. + examples: + response: + value: { + "errcode": "M_INCOMPATIBLE_ROOM_VERSION", + "error": "Your homeserver does not support the features required to join this room", + "room_version": "3" + } + "403": description: |- The room that the joining server is attempting to join does not permit the user to join. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "You are not invited to this room", - } - 404: - schema: - $ref: "../client-server/definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You are not invited to this room" + } + "404": description: |- The room that the joining server is attempting to join is unknown to the receiving server. - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Unknown room", - } - + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Unknown room" + } "/send_join/{roomId}/{eventId}": put: summary: Submit a signed join event to a resident server @@ -236,150 +245,173 @@ paths: parameters: - in: path name: roomId - type: string description: The room ID that is about to be joined. required: true - x-example: "!abc123:matrix.org" + example: "!abc123:matrix.org" + schema: + type: string - in: path name: eventId - type: string description: The event ID for the join event. required: true - x-example: "$abc123:example.org" - - in: body - name: body - type: object - required: true + example: $abc123:example.org schema: - type: object - properties: - sender: - type: string - description: The user ID of the joining member. - example: "@someone:example.org" - origin: - type: string - description: The name of the joining homeserver. - example: "matrix.org" - origin_server_ts: - type: integer - format: int64 - description: A timestamp added by the joining homeserver. - example: 1234567890 - type: - type: string - description: The value `m.room.member`. - example: "m.room.member" - state_key: - type: string - description: The user ID of the joining member. - example: "@someone:example.org" - content: - type: object - title: Membership Event Content - description: The content of the event. - example: {"membership": "join"} - properties: - membership: - type: string - description: The value `join`. - example: "join" - join_authorised_via_users_server: - type: string - x-addedInMatrixVersion: "1.2" - description: |- - Required if the room is [restricted](/client-server-api/#restricted-rooms) - and is joining through one of the conditions available. If the - user is responding to an invite, this is not required. + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + sender: + type: string + description: The user ID of the joining member. + example: "@someone:example.org" + origin: + type: string + description: The name of the joining homeserver. + example: matrix.org + origin_server_ts: + type: integer + format: int64 + description: A timestamp added by the joining homeserver. + example: 1234567890 + type: + type: string + description: The value `m.room.member`. + example: m.room.member + state_key: + type: string + description: The user ID of the joining member. + example: "@someone:example.org" + content: + type: object + title: Membership Event Content + description: The content of the event. + example: + membership: join + properties: + membership: + type: string + description: The value `join`. + example: join + join_authorised_via_users_server: + type: string + x-addedInMatrixVersion: "1.2" + description: |- + Required if the room is [restricted](/client-server-api/#restricted-rooms) + and is joining through one of the conditions available. If the + user is responding to an invite, this is not required. - An arbitrary user ID belonging to the resident server in - the room being joined that is able to issue invites to other - users. This is used in later validation of the auth rules for - the `m.room.member` event. + An arbitrary user ID belonging to the resident server in + the room being joined that is able to issue invites to other + users. This is used in later validation of the auth rules for + the `m.room.member` event. - The resident server which owns the provided user ID must have a - valid signature on the event. If the resident server is receiving - the `/send_join` request, the signature must be added before sending - or persisting the event to other servers. - required: ['membership'] - required: - - state_key - - sender - - origin - - origin_server_ts - - type - - content - example: { - "room_id": "!somewhere:example.org", - "type": "m.room.member", - "state_key": "@someone:example.org", - "origin": "example.org", - "origin_server_ts": 1549041175876, - "sender": "@someone:example.org", - "content": { - "membership": "join", - "join_authorised_via_users_server": "@anyone:resident.example.org" - } - } + The resident server which owns the provided user ID must have a + valid signature on the event. If the resident server is receiving + the `/send_join` request, the signature must be added before sending + or persisting the event to other servers. + required: + - membership + required: + - state_key + - sender + - origin + - origin_server_ts + - type + - content + required: true responses: - 200: - description: |- - The join event has been accepted into the room. - schema: - type: array - minItems: 2 - maxItems: 2 - items: - - type: integer - description: The value `200`. - example: 200 - - type: object - title: Room State - description: The state for the room. - properties: - origin: - type: string - description: The resident server's DNS name. - auth_chain: - type: array - description: |- - The auth chain for the entire current room state prior to the join event. + "200": + description: The join event has been accepted into the room. + content: + application/json: + schema: + type: array + minItems: 2 + maxItems: 2 + items: + anyOf: + - type: integer + description: The value `200`. + example: 200 + - type: object + title: Room State + description: The state for the room. + properties: + origin: + type: string + description: The resident server's DNS name. + auth_chain: + type: array + description: |- + The auth chain for the entire current room state prior to the join event. - Note that events have a different format depending on the room version - check the - [room version specification](/rooms) for precise event formats. - items: - type: object - title: PDU - description: |- - The [PDUs](/server-server-api/#pdus) that make up the auth chain. The event format varies depending - on the room version - check the [room version specification](/rooms) for precise event formats. - schema: - type: object - properties: {} - state: - type: array - description: |- - The resolved current room state prior to the join event. + Note that events have a different format depending on the room version - check the + [room version specification](/rooms) for precise event formats. + items: + type: object + title: PDU + description: |- + The [PDUs](/server-server-api/#pdus) that make up the auth chain. The event format varies depending + on the room version - check the [room version specification](/rooms) for precise event formats. + schema: + type: object + properties: {} + state: + type: array + description: |- + The resolved current room state prior to the join event. - The event format varies depending on the room version - check the [room version specification](/rooms) - for precise event formats. - items: - type: object - title: PDU - description: |- - The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format varies depending - on the room version - check the [room version specification](/rooms) for precise event formats. - schema: - type: object - properties: {} - required: ["auth_chain", "state", "origin"] - examples: - application/json: [ - 200, - { - "origin": "matrix.org", - "auth_chain": [{"$ref": "examples/minimal_pdu.json"}], - "state": [{"$ref": "examples/minimal_pdu.json"}], - "event": {"$ref": "examples/pdu_v4_join_membership.json"} - } - ] + The event format varies depending on the room version - check the [room version specification](/rooms) + for precise event formats. + items: + type: object + title: PDU + description: |- + The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format varies depending + on the room version - check the [room version specification](/rooms) for precise event formats. + schema: + type: object + properties: {} + required: + - auth_chain + - state + - origin + examples: + response: + value: [ + 200, + { + "origin": "matrix.org", + "auth_chain": [ + { + "$ref": "examples/minimal_pdu.json" + } + ], + "state": [ + { + "$ref": "examples/minimal_pdu.json" + } + ], + "event": { + "$ref": "examples/pdu_v4_join_membership.json" + } + } + ] +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/joins-v2.yaml b/data/api/server-server/joins-v2.yaml index 3a8a47b17..d4f26cca2 100644 --- a/data/api/server-server/joins-v2.yaml +++ b/data/api/server-server/joins-v2.yaml @@ -12,23 +12,11 @@ # 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 Federation Join Room API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v2 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation Join Room API + version: 1.0.0 paths: - # Note: there is no v2 of make_join (yet) "/send_join/{roomId}/{eventId}": put: summary: Submit a signed join event to a resident server @@ -55,19 +43,20 @@ paths: parameters: - in: path name: roomId - type: string description: The room ID that is about to be joined. required: true - x-example: "!abc123:matrix.org" + example: "!abc123:matrix.org" + schema: + type: string - in: path name: eventId - type: string description: The event ID for the join event. required: true - x-example: "$abc123:example.org" + example: $abc123:example.org + schema: + type: string - in: query name: omit_members - type: boolean description: |- If `true`, indicates that that calling server can accept a reduced response, in which membership events are omitted from `state` and @@ -83,83 +72,174 @@ paths: response `state` field, and include the auth chains for these membership events in the response `auth_chain` field. x-addedInMatrixVersion: "1.6" - - in: body - name: body - type: object - required: true schema: - type: object - properties: - sender: - type: string - description: The user ID of the joining member. - example: "@someone:example.org" - origin: - type: string - description: The name of the joining homeserver. - example: "matrix.org" - origin_server_ts: - type: integer - format: int64 - description: A timestamp added by the joining homeserver. - example: 1234567890 - type: - type: string - description: The value `m.room.member`. - example: "m.room.member" - state_key: - type: string - description: The user ID of the joining member. - example: "@someone:example.org" - content: + type: boolean + requestBody: + content: + application/json: + schema: + type: object + properties: + sender: + type: string + description: The user ID of the joining member. + example: "@someone:example.org" + origin: + type: string + description: The name of the joining homeserver. + example: matrix.org + origin_server_ts: + type: integer + format: int64 + description: A timestamp added by the joining homeserver. + example: 1234567890 + type: + type: string + description: The value `m.room.member`. + example: m.room.member + state_key: + type: string + description: The user ID of the joining member. + example: "@someone:example.org" + content: + type: object + title: Membership Event Content + description: The content of the event. + example: + membership: join + properties: + membership: + type: string + description: The value `join`. + example: join + join_authorised_via_users_server: + type: string + x-addedInMatrixVersion: "1.2" + description: |- + Required if the room is [restricted](/client-server-api/#restricted-rooms) + and is joining through one of the conditions available. If the + user is responding to an invite, this is not required. + + An arbitrary user ID belonging to the resident server in + the room being joined that is able to issue invites to other + users. This is used in later validation of the auth rules for + the `m.room.member` event. + + The resident server which owns the provided user ID must have a + valid signature on the event. If the resident server is receiving + the `/send_join` request, the signature must be added before sending + or persisting the event to other servers. + required: + - membership + required: + - state_key + - sender + - origin + - origin_server_ts + - type + - content + required: true + responses: + "200": + description: The join event has been accepted into the room. + content: + application/json: + schema: type: object - title: Membership Event Content - description: The content of the event. - example: {"membership": "join"} properties: - membership: + origin: type: string - description: The value `join`. - example: "join" - join_authorised_via_users_server: - type: string - x-addedInMatrixVersion: "1.2" + description: The resident server's DNS name. + members_omitted: + type: boolean + description: "`true` if `m.room.member` events have been omitted from `state`." + x-addedInMatrixVersion: "1.6" + auth_chain: + type: array description: |- - Required if the room is [restricted](/client-server-api/#restricted-rooms) - and is joining through one of the conditions available. If the - user is responding to an invite, this is not required. + All events in the auth chain for the new join event, as well + as those in the auth chains for any events returned in + `state`. - An arbitrary user ID belonging to the resident server in - the room being joined that is able to issue invites to other - users. This is used in later validation of the auth rules for - the `m.room.member` event. + If the `omit_members` query parameter was set to `true`, then + any events that are returned in `state` may be omitted from + `auth_chain`, whether or not membership events are omitted + from `state`. - The resident server which owns the provided user ID must have a - valid signature on the event. If the resident server is receiving - the `/send_join` request, the signature must be added before sending - or persisting the event to other servers. - required: ['membership'] - required: - - state_key - - sender - - origin - - origin_server_ts - - type - - content - example: { - "room_id": "!somewhere:example.org", - "type": "m.room.member", - "state_key": "@someone:example.org", - "origin": "example.org", - "origin_server_ts": 1549041175876, - "sender": "@someone:example.org", - "content": { - "membership": "join", - "join_authorised_via_users_server": "@anyone:resident.example.org" - } - } - responses: - 400: + Note that events have a different format depending on the room version - check the + [room version specification](/rooms) for precise event formats. + items: + type: object + title: PDU + schema: + type: object + properties: {} + x-changedInMatrixVersion: + "1.6": |- + reworded to include only consider state events returned in + `state`, and to allow elision of redundant events. + state: + type: array + description: |- + The resolved current room state prior to the join event. + + If the request had `omit_members` set to `true`, events of + type `m.room.member` may be omitted from the response to + reduce the size of the response. If this is done, + `members_omitted` must be set to `true`. + items: + type: object + title: PDU + schema: + type: object + properties: {} + x-changedInMatrixVersion: + "1.6": permit omission of membership events. + event: + type: object + title: SignedMembershipEvent + x-addedInMatrixVersion: "1.2" + description: |- + Required if the room version [supports restricted join rules](/rooms/#feature-matrix). The signed + copy of the membership event sent to other servers by the resident server, including the resident + server's signature. + servers_in_room: + type: array + x-addedInMatrixVersion: "1.6" + description: |- + **Required** if `members_omitted` is true. + + A list of the servers active in the room (ie, those with joined members) before the join. + items: + type: string + required: + - auth_chain + - state + - origin + examples: + response: + value: { + "origin": "matrix.org", + "auth_chain": [ + { + "$ref": "examples/minimal_pdu.json" + } + ], + "state": [ + { + "$ref": "examples/minimal_pdu.json" + } + ], + "event": { + "$ref": "examples/pdu_v4_join_membership.json" + }, + "members_omitted": true, + "servers_in_room": [ + "matrix.org", + "example.com" + ] + } + "400": description: |- The request is invalid in some way. @@ -182,103 +262,42 @@ paths: resident server would be unable to meet the auth rules governing `join_authorised_via_users_server` on the resulting `m.room.member` event. - schema: - $ref: "../client-server/definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_UNABLE_TO_GRANT_JOIN", - "error": "This server cannot send invites to you." - } - 403: - schema: - $ref: "../client-server/definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_UNABLE_TO_GRANT_JOIN", + "error": "This server cannot send invites to you." + } + "403": description: |- The room that the joining server is attempting to join does not permit the user to join. - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "You are not invited to this room", - } - 200: - description: |- - The join event has been accepted into the room. - schema: - type: object - properties: - origin: - type: string - description: The resident server's DNS name. - members_omitted: - type: boolean - description: "`true` if `m.room.member` events have been omitted from `state`." - x-addedInMatrixVersion: "1.6" - auth_chain: - type: array - description: |- - All events in the auth chain for the new join event, as well - as those in the auth chains for any events returned in - `state`. - - If the `omit_members` query parameter was set to `true`, then - any events that are returned in `state` may be omitted from - `auth_chain`, whether or not membership events are omitted - from `state`. - - Note that events have a different format depending on the room version - check the - [room version specification](/rooms) for precise event formats. - items: - type: object - title: PDU - schema: - type: object - properties: {} - x-changedInMatrixVersion: - "1.6": |- - reworded to include only consider state events returned in - `state`, and to allow elision of redundant events. - state: - type: array - description: |- - The resolved current room state prior to the join event. - - If the request had `omit_members` set to `true`, events of - type `m.room.member` may be omitted from the response to - reduce the size of the response. If this is done, - `members_omitted` must be set to `true`. - items: - type: object - title: PDU - schema: - type: object - properties: {} - x-changedInMatrixVersion: - "1.6": |- - permit omission of membership events. - event: - type: object - title: SignedMembershipEvent - x-addedInMatrixVersion: "1.2" - description: |- - Required if the room version [supports restricted join rules](/rooms/#feature-matrix). The signed - copy of the membership event sent to other servers by the resident server, including the resident - server's signature. - servers_in_room: - type: array - x-addedInMatrixVersion: "1.6" - description: |- - **Required** if `members_omitted` is true. - - A list of the servers active in the room (ie, those with joined members) before the join. - items: - type: string - required: ["auth_chain", "state", "origin"] - examples: - application/json: { - "origin": "matrix.org", - "auth_chain": [{"$ref": "examples/minimal_pdu.json"}], - "state": [{"$ref": "examples/minimal_pdu.json"}], - "event": {"$ref": "examples/pdu_v4_join_membership.json"}, - "members_omitted": true, - "servers_in_room": ["matrix.org", "example.com"] - } + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You are not invited to this room" + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v2 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/keys_query.yaml b/data/api/server-server/keys_query.yaml index 5857ce319..b639a2a84 100644 --- a/data/api/server-server/keys_query.yaml +++ b/data/api/server-server/keys_query.yaml @@ -11,19 +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 Federation Key Exchange API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/key/v2 -consumes: - - application/json -produces: - - application/json + title: Matrix Federation Key Exchange API + version: 1.0.0 paths: "/query/{serverName}": get: @@ -35,88 +26,107 @@ paths: parameters: - in: path name: serverName - type: string description: The server's DNS name to query required: true - x-example: matrix.org + example: matrix.org + schema: + type: string - in: query name: minimum_valid_until_ts - type: integer - format: int64 description: |- A millisecond POSIX timestamp in milliseconds indicating when the returned certificates will need to be valid until to be useful to the requesting server. If not supplied, the current time as determined by the notary server is used. required: false - x-example: 1234567890 + example: 1234567890 + schema: + type: integer + format: int64 responses: - 200: + "200": description: |- The keys for the server, or an empty array if the server could not be reached and no cached keys were available. - schema: - $ref: "definitions/keys_query_response.yaml" - "/query": + content: + application/json: + schema: + $ref: definitions/keys_query_response.yaml + /query: post: summary: Query for several server's keys description: |- Query for keys from multiple servers in a batch format. The receiving (notary) server must sign the keys returned by the queried servers. operationId: bulkPerspectivesKeyQuery - parameters: - - in: body - name: body - schema: - type: object - example: { - "server_keys": { - "example.org": { - "ed25519:abc123": { - "minimum_valid_until_ts": 1234567890 + requestBody: + content: + application/json: + schema: + type: object + example: { + "server_keys": { + "example.org": { + "ed25519:abc123": { + "minimum_valid_until_ts": 1234567890 + } } } } - } - properties: - server_keys: - type: object - description: |- - The query criteria. The outer `string` key on the object is the - server name (eg: `matrix.org`). The inner `string` key is the - Key ID to query for the particular server. If no key IDs are given - to be queried, the notary server should query for all keys. If no - servers are given, the notary server must return an empty `server_keys` - array in the response. - - The notary server may return multiple keys regardless of the Key IDs - given. - additionalProperties: + properties: + server_keys: type: object - name: ServerName - description: The server names to query. + description: |- + The query criteria. The outer `string` key on the object is the + server name (eg: `matrix.org`). The inner `string` key is the + Key ID to query for the particular server. If no key IDs are given + to be queried, the notary server should query for all keys. If no + servers are given, the notary server must return an empty `server_keys` + array in the response. + + The notary server may return multiple keys regardless of the Key IDs + given. additionalProperties: type: object - title: Query Criteria - description: The server key IDs to query. - properties: - minimum_valid_until_ts: - type: integer - format: int64 - description: |- - A millisecond POSIX timestamp in milliseconds indicating when - the returned certificates will need to be valid until to be - useful to the requesting server. + name: ServerName + description: The server names to query. + additionalProperties: + type: object + title: Query Criteria + description: The server key IDs to query. + properties: + minimum_valid_until_ts: + type: integer + format: int64 + description: |- + A millisecond POSIX timestamp in milliseconds indicating when + the returned certificates will need to be valid until to be + useful to the requesting server. - If not supplied, the current time as determined by the notary - server is used. - example: 1234567890 - required: ['server_keys'] + If not supplied, the current time as determined by the notary + server is used. + example: 1234567890 + required: + - server_keys responses: - 200: + "200": description: |- The keys for the queried servers, signed by the notary server. Servers which are offline and have no cached keys will not be included in the result. This may result in an empty array. - schema: - $ref: "definitions/keys_query_response.yaml" + content: + application/json: + schema: + $ref: definitions/keys_query_response.yaml +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/key/v2 diff --git a/data/api/server-server/keys_server.yaml b/data/api/server-server/keys_server.yaml index bee520f35..8929458dc 100644 --- a/data/api/server-server/keys_server.yaml +++ b/data/api/server-server/keys_server.yaml @@ -11,19 +11,12 @@ # 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 Federation Key Exchange API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/key/v2 -produces: - - application/json + title: Matrix Federation Key Exchange API + version: 1.0.0 paths: - "/server": + /server: get: summary: Get the homeserver's public key(s) description: |- @@ -44,7 +37,21 @@ paths: checked. operationId: getServerKey responses: - 200: + "200": description: The homeserver's keys - schema: - $ref: "definitions/keys.yaml" + content: + application/json: + schema: + $ref: definitions/keys.yaml +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/key/v2 diff --git a/data/api/server-server/knocks.yaml b/data/api/server-server/knocks.yaml index de17f44df..bab56d95a 100644 --- a/data/api/server-server/knocks.yaml +++ b/data/api/server-server/knocks.yaml @@ -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 Federation Knock Room API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation Knock Room API + version: 1.0.0 paths: "/make_knock/{roomId}/{userId}": get: @@ -40,107 +29,117 @@ paths: parameters: - in: path name: roomId - type: string description: The room ID that is about to be knocked. required: true - x-example: "!abc123:example.org" + example: "!abc123:example.org" + schema: + type: string - in: path name: userId - type: string description: The user ID the knock event will be for. required: true - x-example: "@someone:example.org" - - in: query - type: array - items: + example: "@someone:example.org" + schema: type: string + - in: query name: ver - description: |- - The room versions the sending server has support for. - required: true # knocking was supported in v7 - x-example: ["1", "7"] + description: The room versions the sending server has support for. + required: true + example: + - "1" + - "7" + style: form + explode: false + schema: + type: array + items: + type: string responses: - 200: + "200": description: |- A template to be used for the rest of the [Knocking Rooms](/server-server-api/#knocking-rooms) handshake. Note that events have a different format depending on room version - check the [room version specification](/rooms) for precise event formats. **The response body here describes the common event fields in more detail and may be missing other required fields for a PDU.** - schema: - type: object - properties: - room_version: - type: string - description: |- - The version of the room where the server is trying to knock. - example: "7" - event: - description: |- - An unsigned template event. Note that events have a different format - depending on the room version - check the [room version specification](/rooms) - for precise event formats. + content: + application/json: + schema: type: object - title: Event Template properties: - sender: - type: string - description: The user ID of the knocking member. - example: "@someone:example.org" - origin: - type: string - description: The name of the resident homeserver. - example: "matrix.org" - origin_server_ts: - type: integer - format: int64 - description: A timestamp added by the resident homeserver. - example: 1234567890 - type: - type: string - description: The value `m.room.member`. - example: "m.room.member" - state_key: + room_version: type: string - description: The user ID of the knocking member. - example: "@someone:example.org" - content: + description: The version of the room where the server is trying to knock. + example: "7" + event: + description: |- + An unsigned template event. Note that events have a different format + depending on the room version - check the [room version specification](/rooms) + for precise event formats. type: object - title: Membership Event Content - description: The content of the event. - example: {"membership": "knock"} + title: Event Template properties: - membership: + sender: + type: string + description: The user ID of the knocking member. + example: "@someone:example.org" + origin: + type: string + description: The name of the resident homeserver. + example: matrix.org + origin_server_ts: + type: integer + format: int64 + description: A timestamp added by the resident homeserver. + example: 1234567890 + type: + type: string + description: The value `m.room.member`. + example: m.room.member + state_key: type: string - description: The value `knock`. - example: "knock" - required: ['membership'] + description: The user ID of the knocking member. + example: "@someone:example.org" + content: + type: object + title: Membership Event Content + description: The content of the event. + example: + membership: knock + properties: + membership: + type: string + description: The value `knock`. + example: knock + required: + - membership + required: + - state_key + - origin + - origin_server_ts + - type + - content + - sender required: - - state_key - - origin - - origin_server_ts - - type - - content - - sender - required: - - room_version # knocking was added in v7 - - event - examples: - application/json: { - "room_version": "7", - "event": { - "room_id": "!somewhere:example.org", - "type": "m.room.member", - "state_key": "@someone:example.org", - "origin": "example.org", - "origin_server_ts": 1549041175876, - "sender": "@someone:example.org", - "content": { - "membership": "knock" - } - } - } - 400: + - room_version + - event + examples: + response: + value: { + "room_version": "7", + "event": { + "room_id": "!somewhere:example.org", + "type": "m.room.member", + "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "knock" + } + } + } + "400": description: |- The request is invalid or the room the server is attempting to knock upon has a version that is not listed in the `ver` @@ -148,47 +147,55 @@ paths: The error should be passed through to clients so that they may give better feedback to users. - schema: - allOf: - - $ref: "../client-server/definitions/errors/error.yaml" - - type: object - properties: - room_version: - type: string - description: |- - The version of the room. Required if the `errcode` - is `M_INCOMPATIBLE_ROOM_VERSION`. - examples: - application/json: { - "errcode": "M_INCOMPATIBLE_ROOM_VERSION", - "error": "Your homeserver does not support the features required to knock on this room", - "room_version": "7" - } - 404: - description: |- - The room that the knocking server is attempting to knock upon is unknown - to the receiving server. - schema: - allOf: - - $ref: "../client-server/definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Unknown room", - } - 403: + content: + application/json: + schema: + allOf: + - $ref: ../client-server/definitions/errors/error.yaml + - type: object + properties: + room_version: + type: string + description: |- + The version of the room. Required if the `errcode` + is `M_INCOMPATIBLE_ROOM_VERSION`. + examples: + response: + value: { + "errcode": "M_INCOMPATIBLE_ROOM_VERSION", + "error": "Your homeserver does not support the features required to knock on this room", + "room_version": "7" + } + "403": description: |- The knocking server or user is not permitted to knock on the room, such as when the server/user is banned or the room is not set up for receiving knocks. - schema: - allOf: - - $ref: "../client-server/definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "You are not permitted to knock on this room", - } - + content: + application/json: + schema: + allOf: + - $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You are not permitted to knock on this room" + } + "404": + description: |- + The room that the knocking server is attempting to knock upon is unknown + to the receiving server. + content: + application/json: + schema: + allOf: + - $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Unknown room" + } "/send_knock/{roomId}/{eventId}": put: x-addedInMatrixVersion: "1.1" @@ -207,117 +214,136 @@ paths: parameters: - in: path name: roomId - type: string description: The room ID that is about to be knocked upon. required: true - x-example: "!abc123:example.org" + example: "!abc123:example.org" + schema: + type: string - in: path name: eventId - type: string description: The event ID for the knock event. required: true - x-example: "$abc123:example.org" - - in: body - name: body - type: object - required: true + example: $abc123:example.org schema: - type: object - properties: - sender: - type: string - description: The user ID of the knocking member. - example: "@someone:example.org" - origin: - type: string - description: The name of the knocking homeserver. - example: "matrix.org" - origin_server_ts: - type: integer - format: int64 - description: A timestamp added by the knocking homeserver. - example: 1234567890 - type: - type: string - description: The value `m.room.member`. - example: "m.room.member" - state_key: - type: string - description: The user ID of the knocking member. - example: "@someone:example.org" - content: - type: object - title: Membership Event Content - description: The content of the event. - example: {"membership": "knock"} - properties: - membership: - type: string - description: The value `knock`. - example: "knock" - required: ['membership'] - required: - - state_key - - sender - - origin - - origin_server_ts - - type - - content - example: { - "room_id": "!somewhere:example.org", - "type": "m.room.member", - "state_key": "@someone:example.org", - "origin": "example.org", - "origin_server_ts": 1549041175876, - "sender": "@someone:example.org", - "content": { - "membership": "knock" - } - } + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + sender: + type: string + description: The user ID of the knocking member. + example: "@someone:example.org" + origin: + type: string + description: The name of the knocking homeserver. + example: matrix.org + origin_server_ts: + type: integer + format: int64 + description: A timestamp added by the knocking homeserver. + example: 1234567890 + type: + type: string + description: The value `m.room.member`. + example: m.room.member + state_key: + type: string + description: The user ID of the knocking member. + example: "@someone:example.org" + content: + type: object + title: Membership Event Content + description: The content of the event. + example: + membership: knock + properties: + membership: + type: string + description: The value `knock`. + example: knock + required: + - membership + required: + - state_key + - sender + - origin + - origin_server_ts + - type + - content + required: true responses: - 200: + "200": description: |- Information about the room to pass along to clients regarding the knock. - schema: - type: object - properties: - knock_room_state: - type: array - items: - $ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml" - description: |- - A list of [stripped state events](/client-server-api/#stripped-state) - to help the initiator of the knock identify the room. - example: - $ref: "../../event-schemas/examples/knock_room_state.json" - required: ['knock_room_state'] - examples: - application/json: { - "knock_room_state": {"$ref": "../../event-schemas/examples/knock_room_state.json"} - } - 404: - description: |- - The room that the knocking server is attempting to knock upon is unknown - to the receiving server. - schema: - allOf: - - $ref: "../client-server/definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Unknown room", - } - 403: + content: + application/json: + schema: + type: object + properties: + knock_room_state: + type: array + items: + $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml + description: |- + A list of [stripped state events](/client-server-api/#stripped-state) + to help the initiator of the knock identify the room. + example: + $ref: ../../event-schemas/examples/knock_room_state.json + required: + - knock_room_state + examples: + response: + value: { + "knock_room_state": { + "$ref": "../../event-schemas/examples/knock_room_state.json" + } + } + "403": description: |- The knocking server or user is not permitted to knock on the room, such as when the server/user is banned or the room is not set up for receiving knocks. - schema: - allOf: - - $ref: "../client-server/definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "You are not permitted to knock on this room", - } - + content: + application/json: + schema: + allOf: + - $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "You are not permitted to knock on this room" + } + "404": + description: |- + The room that the knocking server is attempting to knock upon is unknown + to the receiving server. + content: + application/json: + schema: + allOf: + - $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Unknown room" + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/leaving-v1.yaml b/data/api/server-server/leaving-v1.yaml index 40c8a0627..c339cc033 100644 --- a/data/api/server-server/leaving-v1.yaml +++ b/data/api/server-server/leaving-v1.yaml @@ -12,21 +12,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 Federation Leave Room API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation Leave Room API + version: 1.0.0 paths: "/make_leave/{roomId}/{userId}": get: @@ -40,105 +29,115 @@ paths: parameters: - in: path name: roomId - type: string description: The room ID that is about to be left. required: true - x-example: "!abc123:matrix.org" + example: "!abc123:matrix.org" + schema: + type: string - in: path name: userId - type: string description: The user ID the leave event will be for. required: true - x-example: "@someone:example.org" + example: "@someone:example.org" + schema: + type: string responses: - 200: + "200": description: |- A template to be used to call `/send_leave`. Note that events have a different format depending on the room version - check the [room version specification](/rooms) for precise event formats. **The response body here describes the common event fields in more detail and may be missing other required fields for a PDU.** - schema: - type: object - properties: - room_version: - type: string - description: |- - The version of the room where the server is trying to leave. If not provided, - the room version is assumed to be either "1" or "2". - example: "2" - event: - description: |- - An unsigned template event. Note that events have a different format - depending on the room version - check the [room version specification](/rooms) - for precise event formats. + content: + application/json: + schema: type: object - title: Event Template properties: - sender: - type: string - description: The user ID of the leaving member. - example: "@someone:example.org" - origin: + room_version: type: string - description: The name of the resident homeserver. - example: "matrix.org" - origin_server_ts: - type: integer - format: int64 - description: A timestamp added by the resident homeserver. - example: 1234567890 - type: - type: string - description: The value `m.room.member`. - example: "m.room.member" - state_key: - type: string - description: The user ID of the leaving member. - example: "@someone:example.org" - content: + description: |- + The version of the room where the server is trying to leave. If not provided, + the room version is assumed to be either "1" or "2". + example: "2" + event: + description: |- + An unsigned template event. Note that events have a different format + depending on the room version - check the [room version specification](/rooms) + for precise event formats. type: object - title: Membership Event Content - description: The content of the event. - example: {"membership": "leave"} + title: Event Template properties: - membership: + sender: type: string - description: The value `leave`. - example: "leave" - required: ['membership'] - required: - - state_key - - sender - - origin - - origin_server_ts - - type - - content - examples: - application/json: { - "room_version": "2", - "event": { - "room_id": "!somewhere:example.org", - "type": "m.room.member", - "state_key": "@someone:example.org", - "origin": "example.org", - "origin_server_ts": 1549041175876, - "sender": "@someone:example.org", - "content": { - "membership": "leave" - } - } - } - 403: - description: |- - The request is not authorized. This could mean that the user is not in the room. - schema: - $ref: "../client-server/definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_FORBIDDEN", - "error": "User is not in the room." - } + description: The user ID of the leaving member. + example: "@someone:example.org" + origin: + type: string + description: The name of the resident homeserver. + example: matrix.org + origin_server_ts: + type: integer + format: int64 + description: A timestamp added by the resident homeserver. + example: 1234567890 + type: + type: string + description: The value `m.room.member`. + example: m.room.member + state_key: + type: string + description: The user ID of the leaving member. + example: "@someone:example.org" + content: + type: object + title: Membership Event Content + description: The content of the event. + example: + membership: leave + properties: + membership: + type: string + description: The value `leave`. + example: leave + required: + - membership + required: + - state_key + - sender + - origin + - origin_server_ts + - type + - content + examples: + response: + value: { + "room_version": "2", + "event": { + "room_id": "!somewhere:example.org", + "type": "m.room.member", + "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "leave" + } + } + } + "403": + description: The request is not authorized. This could mean that the user is not + in the room. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "User is not in the room." + } "/send_leave/{roomId}/{eventId}": put: summary: Submit a signed leave event to a resident server @@ -159,93 +158,108 @@ paths: parameters: - in: path name: roomId - type: string description: The room ID that is about to be left. required: true - x-example: "!abc123:matrix.org" + example: "!abc123:matrix.org" + schema: + type: string - in: path name: eventId - type: string description: The event ID for the leave event. required: true - x-example: "$abc123:example.org" - - in: body - name: body - type: object - required: true + example: $abc123:example.org schema: - type: object - properties: - sender: - type: string - description: The user ID of the leaving member. - example: "@someone:example.org" - origin: - type: string - description: The name of the leaving homeserver. - example: "matrix.org" - origin_server_ts: - type: integer - format: int64 - description: A timestamp added by the leaving homeserver. - example: 1234567890 - type: - type: string - description: The value `m.room.member`. - example: "m.room.member" - state_key: - type: string - description: The user ID of the leaving member. - example: "@someone:example.org" - content: - type: object - title: Membership Event Content - description: The content of the event. - example: {"membership": "leave"} - properties: - membership: - type: string - description: The value `leave`. - example: "leave" - required: ['membership'] - depth: - type: integer - description: This field must be present but is ignored; it may be 0. - example: 12 - required: - - state_key - - sender - - origin - - origin_server_ts - - type - - depth - - content - example: { - "room_id": "!somewhere:example.org", - "type": "m.room.member", - "state_key": "@someone:example.org", - "origin": "example.org", - "origin_server_ts": 1549041175876, - "sender": "@someone:example.org", - "content": { - "membership": "leave" - } - } + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + sender: + type: string + description: The user ID of the leaving member. + example: "@someone:example.org" + origin: + type: string + description: The name of the leaving homeserver. + example: matrix.org + origin_server_ts: + type: integer + format: int64 + description: A timestamp added by the leaving homeserver. + example: 1234567890 + type: + type: string + description: The value `m.room.member`. + example: m.room.member + state_key: + type: string + description: The user ID of the leaving member. + example: "@someone:example.org" + content: + type: object + title: Membership Event Content + description: The content of the event. + example: + membership: leave + properties: + membership: + type: string + description: The value `leave`. + example: leave + required: + - membership + depth: + type: integer + description: This field must be present but is ignored; it may be 0. + example: 12 + required: + - state_key + - sender + - origin + - origin_server_ts + - type + - depth + - content + required: true responses: - 200: + "200": description: |- An empty response to indicate the event was accepted into the graph by the receiving homeserver. - schema: - type: array - minItems: 2 - maxItems: 2 - items: - - type: integer - description: The value `200`. - example: 200 - - type: object - title: Empty Object - description: An empty object. - examples: - application/json: [200, {}] + content: + application/json: + schema: + type: array + minItems: 2 + maxItems: 2 + items: + anyOf: + - type: integer + description: The value `200`. + example: 200 + - type: object + title: Empty Object + description: An empty object. + examples: + response: + value: [ + 200, + {} + ] +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/leaving-v2.yaml b/data/api/server-server/leaving-v2.yaml index dd96eaaa3..6701c7c1f 100644 --- a/data/api/server-server/leaving-v2.yaml +++ b/data/api/server-server/leaving-v2.yaml @@ -12,23 +12,11 @@ # 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 Federation Leave Room API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v2 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation Leave Room API + version: 1.0.0 paths: - # Note: there is no v2 of make_leave (yet) "/send_leave/{roomId}/{eventId}": put: summary: Submit a signed leave event to a resident server @@ -55,86 +43,97 @@ paths: parameters: - in: path name: roomId - type: string description: The room ID that is about to be left. required: true - x-example: "!abc123:matrix.org" + example: "!abc123:matrix.org" + schema: + type: string - in: path name: eventId - type: string description: The event ID for the leave event. required: true - x-example: "$abc123:example.org" - - in: body - name: body - type: object - required: true + example: $abc123:example.org schema: - type: object - properties: - sender: - type: string - description: The user ID of the leaving member. - example: "@someone:example.org" - origin: - type: string - description: The name of the leaving homeserver. - example: "matrix.org" - origin_server_ts: - type: integer - format: int64 - description: A timestamp added by the leaving homeserver. - example: 1234567890 - type: - type: string - description: The value `m.room.member`. - example: "m.room.member" - state_key: - type: string - description: The user ID of the leaving member. - example: "@someone:example.org" - content: - type: object - title: Membership Event Content - description: The content of the event. - example: {"membership": "leave"} - properties: - membership: - type: string - description: The value `leave`. - example: "leave" - required: ['membership'] - depth: - type: integer - description: This field must be present but is ignored; it may be 0. - example: 12 - required: - - state_key - - sender - - origin - - origin_server_ts - - type - - depth - - content - example: { - "room_id": "!somewhere:example.org", - "type": "m.room.member", - "state_key": "@someone:example.org", - "origin": "example.org", - "origin_server_ts": 1549041175876, - "sender": "@someone:example.org", - "content": { - "membership": "leave" - } - } + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + sender: + type: string + description: The user ID of the leaving member. + example: "@someone:example.org" + origin: + type: string + description: The name of the leaving homeserver. + example: matrix.org + origin_server_ts: + type: integer + format: int64 + description: A timestamp added by the leaving homeserver. + example: 1234567890 + type: + type: string + description: The value `m.room.member`. + example: m.room.member + state_key: + type: string + description: The user ID of the leaving member. + example: "@someone:example.org" + content: + type: object + title: Membership Event Content + description: The content of the event. + example: + membership: leave + properties: + membership: + type: string + description: The value `leave`. + example: leave + required: + - membership + depth: + type: integer + description: This field must be present but is ignored; it may be 0. + example: 12 + required: + - state_key + - sender + - origin + - origin_server_ts + - type + - depth + - content + required: true responses: - 200: + "200": description: |- An empty response to indicate the event was accepted into the graph by the receiving homeserver. - schema: - type: object - title: Empty Object - description: An empty object. - examples: - application/json: {} + content: + application/json: + schema: + type: object + title: Empty Object + description: An empty object. + examples: + response: + value: {} +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v2 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/openid.yaml b/data/api/server-server/openid.yaml index 0761618d9..ce7d8866b 100644 --- a/data/api/server-server/openid.yaml +++ b/data/api/server-server/openid.yaml @@ -12,19 +12,12 @@ # 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 Federation OpenID API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -produces: - - application/json + title: Matrix Federation OpenID API + version: 1.0.0 paths: - "/openid/userinfo": + /openid/userinfo: get: summary: Exchange an OpenID token for user information description: |- @@ -35,29 +28,46 @@ paths: parameters: - in: query name: access_token - type: string - description: |- - The OpenID access token to get information about the owner for. + description: The OpenID access token to get information about the owner for. required: true - x-example: SomeT0kenHere - responses: - 200: - description: |- - Information about the user who generated the OpenID access token. + example: SomeT0kenHere schema: - type: object - properties: - sub: - type: string - description: The Matrix User ID who generated the token. - example: "@alice:example.com" - required: ['sub'] - 401: + type: string + responses: + "200": + description: Information about the user who generated the OpenID access token. + content: + application/json: + schema: + type: object + properties: + sub: + type: string + description: The Matrix User ID who generated the token. + example: "@alice:example.com" + required: + - sub + "401": description: The token was not recognized or has expired. - schema: - $ref: "../client-server/definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_UNKNOWN_TOKEN", - "error": "Access token unknown or expired" - } + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_UNKNOWN_TOKEN", + "error": "Access token unknown or expired" + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 diff --git a/data/api/server-server/public_rooms.yaml b/data/api/server-server/public_rooms.yaml index 3079b7c2a..4e0c7a1f7 100644 --- a/data/api/server-server/public_rooms.yaml +++ b/data/api/server-server/public_rooms.yaml @@ -11,21 +11,12 @@ # 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 Federation Public Rooms API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation Public Rooms API + version: 1.0.0 paths: - "/publicRooms": + /publicRooms: get: summary: Get all the public rooms for a homeserver description: |- @@ -38,36 +29,41 @@ paths: parameters: - in: query name: limit - type: integer - description: |- - The maximum number of rooms to return. Defaults to 0 (no limit). - x-example: 10 + description: The maximum number of rooms to return. Defaults to 0 (no limit). + example: 10 + schema: + type: integer - in: query name: since - type: string description: |- A pagination token from a previous call to this endpoint to fetch more rooms. - x-example: "GetMoreRoomsTokenHere" + example: GetMoreRoomsTokenHere + schema: + type: string - in: query name: include_all_networks - type: boolean description: |- Whether or not to include all networks/protocols defined by application services on the homeserver. Defaults to false. - x-example: false + example: false + schema: + type: boolean - in: query name: third_party_instance_id - type: string description: |- The specific third-party network/protocol to request from the homeserver. Can only be used if `include_all_networks` is false. - x-example: "irc" + example: irc + schema: + type: string responses: - 200: + "200": description: The public room list for the homeserver. - schema: - $ref: "../client-server/definitions/public_rooms_response.yaml" + content: + application/json: + schema: + $ref: ../client-server/definitions/public_rooms_response.yaml post: summary: Gets the public rooms on the server with optional filter. description: |- @@ -81,32 +77,27 @@ paths: operationId: queryPublicRooms security: - signedRequest: [] - parameters: - - in: body - name: body - required: true - description: |- - Options for which rooms to return, or empty object to use defaults. - schema: - type: object - properties: - limit: - type: integer - description: |- - Limit the number of results returned. - since: - type: string - description: |- - A pagination token from a previous request, allowing servers - to get the next (or previous) batch of rooms. The direction - of pagination is specified solely by which token is supplied, - rather than via an explicit flag. - filter: - type: object - title: "Filter" - description: |- - Filter to apply to the results. - properties: + requestBody: + content: + application/json: + schema: + type: object + properties: + limit: + type: integer + description: Limit the number of results returned. + since: + type: string + description: |- + A pagination token from a previous request, allowing servers + to get the next (or previous) batch of rooms. The direction + of pagination is specified solely by which token is supplied, + rather than via an explicit flag. + filter: + type: object + title: Filter + description: Filter to apply to the results. + properties: generic_search_term: type: string description: |- @@ -122,85 +113,108 @@ paths: for. To include rooms without a room type, specify `null` within this list. When not specified, all applicable rooms (regardless of type) are returned. - include_all_networks: - type: boolean - description: |- - Whether or not to include all known networks/protocols from - application services on the homeserver. Defaults to false. - example: false - third_party_instance_id: - type: string - description: |- - The specific third-party network/protocol to request from the - homeserver. Can only be used if `include_all_networks` is false. - example: "irc" - example: { - "limit": 10, - "filter": { - "generic_search_term": "foo", - "room_types": [null, "m.space"] - }, - "include_all_networks": false, - "third_party_instance_id": "irc" - } + include_all_networks: + type: boolean + description: |- + Whether or not to include all known networks/protocols from + application services on the homeserver. Defaults to false. + example: false + third_party_instance_id: + type: string + description: |- + The specific third-party network/protocol to request from the + homeserver. Can only be used if `include_all_networks` is false. + example: irc + example: { + "limit": 10, + "filter": { + "generic_search_term": "foo", + "room_types": [ + null, + "m.space" + ] + }, + "include_all_networks": false, + "third_party_instance_id": "irc" + } + description: Options for which rooms to return, or empty object to use defaults. + required: true responses: - 200: + "200": description: A list of the rooms on the server. - schema: - type: object - description: A list of the rooms on the server. - required: ["chunk"] - properties: - chunk: - title: "PublicRoomsChunks" - type: array - description: A paginated chunk of public rooms. - items: - allOf: - - $ref: "../client-server/definitions/public_rooms_chunk.yaml" - - type: object - properties: - # Override description of join_rule - join_rule: - type: string - description: |- - The room's join rule. When not present, the room is assumed to - be `public`. Note that rooms with `invite` join rules are not - expected here, but rooms with `knock` rules are given their - near-public nature. - next_batch: - type: string - description: |- - A pagination token for the response. The absence of this token - means there are no more results to fetch and the client should - stop paginating. - prev_batch: - type: string - description: |- - A pagination token that allows fetching previous results. The - absence of this token means there are no results before this - batch, i.e. this is the first batch. - total_room_count_estimate: - type: integer - description: |- - An estimate on the total number of public rooms, if the - server has an estimate. - examples: - application/json: { - "chunk": [ - { - "avatar_url": "mxc://bleecker.street/CHEDDARandBRIE", - "guest_can_join": false, - "name": "CHEESE", - "num_joined_members": 37, - "room_id": "!ol19s:bleecker.street", - "topic": "Tasty tasty cheese", - "world_readable": true, - "join_rule": "public", - "room_type": "m.space" - } - ], - "next_batch": "p190q", - "prev_batch": "p1902", - "total_room_count_estimate": 115 - } + content: + application/json: + schema: + type: object + description: A list of the rooms on the server. + required: + - chunk + properties: + chunk: + title: PublicRoomsChunks + type: array + description: A paginated chunk of public rooms. + items: + allOf: + - $ref: ../client-server/definitions/public_rooms_chunk.yaml + - type: object + properties: + join_rule: + type: string + description: |- + The room's join rule. When not present, the room is assumed to + be `public`. Note that rooms with `invite` join rules are not + expected here, but rooms with `knock` rules are given their + near-public nature. + next_batch: + type: string + description: |- + A pagination token for the response. The absence of this token + means there are no more results to fetch and the client should + stop paginating. + prev_batch: + type: string + description: |- + A pagination token that allows fetching previous results. The + absence of this token means there are no results before this + batch, i.e. this is the first batch. + total_room_count_estimate: + type: integer + description: |- + An estimate on the total number of public rooms, if the + server has an estimate. + examples: + response: + value: { + "chunk": [ + { + "avatar_url": "mxc://bleecker.street/CHEDDARandBRIE", + "guest_can_join": false, + "name": "CHEESE", + "num_joined_members": 37, + "room_id": "!ol19s:bleecker.street", + "topic": "Tasty tasty cheese", + "world_readable": true, + "join_rule": "public", + "room_type": "m.space" + } + ], + "next_batch": "p190q", + "prev_batch": "p1902", + "total_room_count_estimate": 115 + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/query.yaml b/data/api/server-server/query.yaml index 42b64ea81..23a6dffd4 100644 --- a/data/api/server-server/query.yaml +++ b/data/api/server-server/query.yaml @@ -12,19 +12,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 Federation Query API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation Query API + version: 1.0.0 paths: "/query/{queryType}": get: @@ -39,15 +30,16 @@ paths: parameters: - in: path name: queryType - type: string description: The type of query to make required: true - x-example: profile + example: profile + schema: + type: string responses: - 200: - description: |- - The query response. The schema varies depending on the query being made. - "/query/directory": + "200": + description: The query response. The schema varies depending on the query being + made. + /query/directory: get: summary: Query for the room ID and resident homeservers for a room alias description: |- @@ -63,50 +55,57 @@ paths: parameters: - in: query name: room_alias - type: string description: The room alias to query. required: true - x-example: "#room_alias:example.org" - responses: - 200: - description: |- - The corresponding room ID and list of known resident homeservers for the room. + example: "#room_alias:example.org" schema: - type: object - properties: - room_id: - type: string - description: The room ID mapped to the queried room alias. - x-example: "!roomid1234:example.org" - servers: - type: array - description: |- - An array of server names that are likely to hold the given room. This - list may or may not include the server answering the query. - items: - type: string - required: - - "room_id" - - "servers" - examples: - application/json: { - "room_id": "!roomid1234:example.org", - "servers": [ - "example.org", - "example.com", - "another.example.com:8449", - ] - } - 404: + type: string + responses: + "200": + description: The corresponding room ID and list of known resident homeservers + for the room. + content: + application/json: + schema: + type: object + properties: + room_id: + type: string + description: The room ID mapped to the queried room alias. + example: "!roomid1234:example.org" + servers: + type: array + description: |- + An array of server names that are likely to hold the given room. This + list may or may not include the server answering the query. + items: + type: string + required: + - room_id + - servers + examples: + response: + value: { + "room_id": "!roomid1234:example.org", + "servers": [ + "example.org", + "example.com", + "another.example.com:8449" + ] + } + "404": description: The room alias was not found. - schema: - $ref: "../client-server/definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Room alias not found." - } - "/query/profile": + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Room alias not found." + } + /query/profile: get: summary: Query for profile information about a given user description: |- @@ -122,20 +121,24 @@ paths: parameters: - in: query name: user_id - type: string description: The user ID to query. required: true - x-example: "@someone:example.org" + example: "@someone:example.org" + schema: + type: string - in: query name: field - type: string - enum: ['displayname', 'avatar_url'] description: |- The field to query. If specified, the server will only return the given field in the response. If not specified, the server will return the full profile for the user. + schema: + type: string + enum: + - displayname + - avatar_url responses: - 200: + "200": description: |- The profile for the user. If a `field` is specified in the request, only the matching field should be included in the response. If no `field` was specified, @@ -144,32 +147,53 @@ paths: If the user does not have a particular field set on their profile, the server should exclude it from the response body or give it the value `null`. - schema: - type: object - properties: - displayname: - type: string - description: |- - The display name of the user. May be omitted if the user does not have a - display name set. - x-example: "John Doe" - avatar_url: - type: string - description: |- - The avatar URL for the user's avatar. May be omitted if the user does not - have an avatar set. - x-example: "mxc://matrix.org/MyC00lAvatar" - examples: - application/json: { - "displayname": "John Doe", - "avatar_url": "mxc://matrix.org/MyC00lAvatar" - } - 404: + content: + application/json: + schema: + type: object + properties: + displayname: + type: string + description: |- + The display name of the user. May be omitted if the user does not have a + display name set. + example: John Doe + avatar_url: + type: string + description: |- + The avatar URL for the user's avatar. May be omitted if the user does not + have an avatar set. + example: mxc://matrix.org/MyC00lAvatar + examples: + response: + value: { + "displayname": "John Doe", + "avatar_url": "mxc://matrix.org/MyC00lAvatar" + } + "404": description: The user does not exist or does not have a profile. - schema: - $ref: "../client-server/definitions/errors/error.yaml" - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "User does not exist." - } + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "User does not exist." + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/space_hierarchy.yaml b/data/api/server-server/space_hierarchy.yaml index 296fb6579..aa98158fc 100644 --- a/data/api/server-server/space_hierarchy.yaml +++ b/data/api/server-server/space_hierarchy.yaml @@ -11,20 +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 Federation Space Hierarchy API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation Space Hierarchy API + version: 1.0.0 paths: "/hierarchy/{roomId}": get: @@ -45,163 +35,199 @@ paths: - signedRequest: [] parameters: - in: path - type: string name: roomId description: The room ID of the space to get a hierarchy for. required: true - x-example: "!space:example.org" + example: "!space:example.org" + schema: + type: string - in: query - type: boolean name: suggested_only description: |- Optional (default `false`) flag to indicate whether or not the server should only consider suggested rooms. Suggested rooms are annotated in their [`m.space.child`](/client-server-api/#mspacechild) event contents. - x-example: true - responses: - 200: - description: |- - The space room and its children. - examples: - application/json: { - "room": { - "room_id": "!space:example.org", - "avatar_url": "mxc://example.org/abcdef", - "guest_can_join": false, - "name": "The First Space", - "topic": "No other spaces were created first, ever", - "world_readable": true, - "join_rule": "public", - "room_type": "m.space", - "num_joined_members": 42, - "canonical_alias": "#general:example.org", - "allowed_room_ids": [], - "children_state": [ - { - "type": "m.space.child", - "state_key": "!a:example.org", - "content": { - "via": ["remote.example.org"] - }, - "sender": "@alice:example.org", - "origin_server_ts": 1629413349153 - } - ] - }, - "inaccessible_children": [ - "!secret:example.org" - ], - "children": [ - { - "room_id": "!second_room:example.org", - "avatar_url": "mxc://example.org/abcdef2", - "guest_can_join": false, - "name": "The ~~First~~ Second Space", - "topic": "Hello world", - "world_readable": true, - "join_rule": "restricted", - "room_type": "m.space", - "num_joined_members": 42, - "canonical_alias": "#general:example.org", - "allowed_room_ids": [ - "!upstream:example.org" - ], - "children_state": [ - { - "type": "m.space.child", - "state_key": "!b:example.org", - "content": { - "via": ["remote.example.org"] - }, - "sender": "@alice:example.org", - "origin_server_ts": 1629422222222 - } - ] - } - ] - } + example: true schema: - type: object - properties: - room: - description: A summary of the room requested. - allOf: - - $ref: "../client-server/definitions/public_rooms_chunk.yaml" - - type: object - properties: - room_type: - type: string - description: |- - The `type` of room (from [`m.room.create`](/client-server-api/#mroomcreate)), if any. - allowed_room_ids: - type: array - items: - type: string - description: |- - If the room is a [restricted room](#restricted-rooms), these are the room IDs which - are specified by the join rules. Empty or omitted otherwise. - children_state: - type: array - description: |- - The [`m.space.child`](/client-server-api/#mspacechild) events of the space-room, represented - as [Stripped State Events](/client-server-api/#stripped-state) with an added - `origin_server_ts` key. - - If the room is not a space-room, this should be empty. - items: - allOf: - - $ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml" - - type: object - properties: - origin_server_ts: - type: integer - format: int64 - description: The `origin_server_ts` for the event. - required: [origin_server_ts] - required: [children_state] - children: - type: array - description: |- - A summary of the space's children. Rooms which the requesting server cannot peek/join will - be excluded. - items: - allOf: - - $ref: "../client-server/definitions/public_rooms_chunk.yaml" - - type: object - properties: - room_type: - type: string - description: |- - The `type` of room (from [`m.room.create`](/client-server-api/#mroomcreate)), if any. - allowed_room_ids: - type: array - items: + type: boolean + responses: + "200": + description: The space room and its children. + content: + application/json: + schema: + type: object + properties: + room: + description: A summary of the room requested. + allOf: + - $ref: ../client-server/definitions/public_rooms_chunk.yaml + - type: object + properties: + room_type: type: string - description: |- - If the room is a [restricted room](#restricted-rooms), these are the room IDs which - are specified by the join rules. Empty or omitted otherwise. - required: [room_type, allowed_room_ids, children_state] - inaccessible_children: - type: array - items: - type: string - description: |- - The list of room IDs the requesting server doesn't have a viable way to peek/join. Rooms which - the responding server cannot provide details on will be outright excluded from the response instead. + description: The `type` of room (from + [`m.room.create`](/client-server-api/#mroomcreate)), + if any. + allowed_room_ids: + type: array + items: + type: string + description: |- + If the room is a [restricted room](#restricted-rooms), these are the room IDs which + are specified by the join rules. Empty or omitted otherwise. + children_state: + type: array + description: |- + The [`m.space.child`](/client-server-api/#mspacechild) events of the space-room, represented + as [Stripped State Events](/client-server-api/#stripped-state) with an added + `origin_server_ts` key. + + If the room is not a space-room, this should be empty. + items: + allOf: + - $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml + - type: object + properties: + origin_server_ts: + type: integer + format: int64 + description: The `origin_server_ts` for the event. + required: + - origin_server_ts + required: + - children_state + children: + type: array + description: |- + A summary of the space's children. Rooms which the requesting server cannot peek/join will + be excluded. + items: + allOf: + - $ref: ../client-server/definitions/public_rooms_chunk.yaml + - type: object + properties: + room_type: + type: string + description: The `type` of room (from + [`m.room.create`](/client-server-api/#mroomcreate)), + if any. + allowed_room_ids: + type: array + items: + type: string + description: |- + If the room is a [restricted room](#restricted-rooms), these are the room IDs which + are specified by the join rules. Empty or omitted otherwise. + required: + - room_type + - allowed_room_ids + - children_state + inaccessible_children: + type: array + items: + type: string + description: |- + The list of room IDs the requesting server doesn't have a viable way to peek/join. Rooms which + the responding server cannot provide details on will be outright excluded from the response instead. - Assuming both the requesting and responding server are well behaved, the requesting server should - consider these room IDs as not accessible from anywhere. They should not be re-requested. - required: [room, children, inaccessible_children] - 404: + Assuming both the requesting and responding server are well behaved, the requesting server should + consider these room IDs as not accessible from anywhere. They should not be re-requested. + required: + - room + - children + - inaccessible_children + examples: + response: + value: { + "room": { + "room_id": "!space:example.org", + "avatar_url": "mxc://example.org/abcdef", + "guest_can_join": false, + "name": "The First Space", + "topic": "No other spaces were created first, ever", + "world_readable": true, + "join_rule": "public", + "room_type": "m.space", + "num_joined_members": 42, + "canonical_alias": "#general:example.org", + "allowed_room_ids": [], + "children_state": [ + { + "type": "m.space.child", + "state_key": "!a:example.org", + "content": { + "via": [ + "remote.example.org" + ] + }, + "sender": "@alice:example.org", + "origin_server_ts": 1629413349153 + } + ] + }, + "inaccessible_children": [ + "!secret:example.org" + ], + "children": [ + { + "room_id": "!second_room:example.org", + "avatar_url": "mxc://example.org/abcdef2", + "guest_can_join": false, + "name": "The ~~First~~ Second Space", + "topic": "Hello world", + "world_readable": true, + "join_rule": "restricted", + "room_type": "m.space", + "num_joined_members": 42, + "canonical_alias": "#general:example.org", + "allowed_room_ids": [ + "!upstream:example.org" + ], + "children_state": [ + { + "type": "m.space.child", + "state_key": "!b:example.org", + "content": { + "via": [ + "remote.example.org" + ] + }, + "sender": "@alice:example.org", + "origin_server_ts": 1629422222222 + } + ] + } + ] + } + "404": description: |- The room is not known to the server or the requesting server is unable to peek/join it (if it were to attempt this). - examples: - application/json: { - "errcode": "M_NOT_FOUND", - "error": "Room does not exist." - } - schema: - "$ref": "../client-server/definitions/errors/error.yaml" + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Room does not exist." + } tags: - Spaces +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/third_party_invite.yaml b/data/api/server-server/third_party_invite.yaml index 55e4d6282..ff8ba3cab 100644 --- a/data/api/server-server/third_party_invite.yaml +++ b/data/api/server-server/third_party_invite.yaml @@ -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 Federation Third-party Invites API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation Third-party Invites API + version: 1.0.0 paths: "/exchange_third_party_invite/{roomId}": put: @@ -41,166 +30,142 @@ paths: parameters: - in: path name: roomId - type: string description: The room ID to exchange a third-party invite in required: true - x-example: "!abc123:matrix.org" - - in: body - name: body - type: object - description: A partial `m.room.member` event - required: true + example: "!abc123:matrix.org" schema: - type: object - properties: - type: - type: string - description: The event type. Must be `m.room.member` - example: "m.room.member" - room_id: - type: string - description: |- - The room ID the event is for. Must match the ID given in - the path. - example: "!abc123:matrix.org" - sender: - type: string - description: |- - The user ID of the user who sent the original `m.room.third_party_invite` - event. - example: "@joe:matrix.org" - state_key: - type: string - description: The user ID of the invited user - example: "@someone:example.org" - content: - type: object - description: The event content - title: Event Content - properties: - membership: - type: string - description: The membership state. Must be `invite` - example: invite - third_party_invite: - type: object - description: The third-party invite - title: Third-party Invite - properties: - display_name: - type: string - description: |- - A name which can be displayed to represent the user instead of their - third-party identifier. - example: "alice" - signed: - type: object - description: |- - A block of content which has been signed, which servers can use to - verify the event. - title: Invite Signatures - properties: - signatures: - type: object - title: Signatures - additionalProperties: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + type: + type: string + description: The event type. Must be `m.room.member` + example: m.room.member + room_id: + type: string + description: |- + The room ID the event is for. Must match the ID given in + the path. + example: "!abc123:matrix.org" + sender: + type: string + description: |- + The user ID of the user who sent the original `m.room.third_party_invite` + event. + example: "@joe:matrix.org" + state_key: + type: string + description: The user ID of the invited user + example: "@someone:example.org" + content: + type: object + description: The event content + title: Event Content + properties: + membership: + type: string + description: The membership state. Must be `invite` + example: invite + third_party_invite: + type: object + description: The third-party invite + title: Third-party Invite + properties: + display_name: + type: string + description: |- + A name which can be displayed to represent the user instead of their + third-party identifier. + example: alice + signed: + type: object + description: |- + A block of content which has been signed, which servers can use to + verify the event. + title: Invite Signatures + properties: + signatures: type: object + title: Signatures additionalProperties: - type: string - description: |- - The server signatures for this event. + type: object + additionalProperties: + type: string + description: |- + The server signatures for this event. - The signature is calculated using the process - described at [Signing JSON](/appendices/#signing-json). - example: { - "magic.forest": { - "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" - } - } - mxid: - type: string - description: The invited matrix user ID - example: "@alice:localhost" - token: - type: string - description: The token used to verify the event - example: abc123 - required: ['signatures', 'mxid', 'token'] - example: { - "mxid": "@alice:localhost", - "token": "abc123", - "signatures": { - "magic.forest": { - "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" - } - } - } - required: ['display_name', 'signed'] - example: { - "display_name": "alice", - "signed": { - "mxid": "@alice:localhost", - "token": "abc123", - "signatures": { - "magic.forest": { - "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" - } - } - } - } - required: ['membership', 'third_party_invite'] - example: { - "membership": "invite", - "third_party_invite": { - "display_name": "alice", - "signed": { - "mxid": "@alice:localhost", - "token": "abc123", - "signatures": { - "magic.forest": { - "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" - } - } - } - } - } - required: - - type - - room_id - - sender - - state_key - - content - example: { - "type": "m.room.member", - "room_id": "!abc123:matrix.org", - "sender": "@joe:matrix.org", - "state_key": "@someone:example.org", - "content": { - "membership": "invite", - "third_party_invite": { - "display_name": "alice", - "signed": { - "mxid": "@alice:localhost", - "token": "abc123", - "signatures": { - "magic.forest": { - "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" - } - } - } - } - } - } + The signature is calculated using the process + described at [Signing JSON](/appendices/#signing-json). + example: + magic.forest: + ed25519:3: fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg + mxid: + type: string + description: The invited matrix user ID + example: "@alice:localhost" + token: + type: string + description: The token used to verify the event + example: abc123 + required: + - signatures + - mxid + - token + example: + mxid: "@alice:localhost" + token: abc123 + signatures: + magic.forest: + ed25519:3: fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg + required: + - display_name + - signed + example: + display_name: alice + signed: + mxid: "@alice:localhost" + token: abc123 + signatures: + magic.forest: + ed25519:3: fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg + required: + - membership + - third_party_invite + example: + membership: invite + third_party_invite: + display_name: alice + signed: + mxid: "@alice:localhost" + token: abc123 + signatures: + magic.forest: + ed25519:3: fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg + required: + - type + - room_id + - sender + - state_key + - content + description: A partial `m.room.member` event + required: true responses: - 200: + "200": description: The invite has been issued successfully. - examples: - application/json: {} - schema: - type: object - description: An empty object - example: {} - "/3pid/onbind": + content: + application/json: + schema: + type: object + description: An empty object + example: {} + examples: + response: + value: {} + /3pid/onbind: put: summary: |- Notifies the server that a third-party identifier has been bound to one @@ -210,116 +175,134 @@ paths: has bound a third-party identifier successfully, including any pending room invites the identity server has been made aware of. operationId: onBindThirdPartyIdentifier - parameters: - - in: body - name: body - type: object - required: true - schema: - type: object - properties: - medium: - type: string - description: |- - The type of third-party identifier. Currently only "email" is - a possible value. - example: "email" - address: - type: string - description: |- - The third-party identifier itself. For example, an email address. - example: "alice@example.com" - mxid: - type: string - description: The user that is now bound to the third-party identifier. - example: "@alice:matrix.org" - invites: - type: array - description: |- - A list of pending invites that the third-party identifier has received. - items: - type: object - title: Third-party Invite - properties: - medium: - type: string - description: |- - The type of third-party invite issues. Currently only - "email" is used. - example: "email" - address: - type: string - description: |- - The third-party identifier that received the invite. - example: "alice@example.com" - mxid: - type: string - description: The now-bound user ID that received the invite. - example: "@alice:matrix.org" - room_id: - type: string - description: The room ID the invite is valid for. - example: "!somewhere:example.org" - sender: - type: string - description: The user ID that sent the invite. - example: "@bob:matrix.org" - # TODO (TravisR): Make this reusable when doing IS spec changes - # also make sure it isn't lying about anything, like the key version - signed: - type: object - title: Identity Server Signatures - description: |- - Signature from the identity server using a long-term private - key. - properties: - mxid: - type: string - description: |- - The user ID that has been bound to the third-party - identifier. - example: "@alice:matrix.org" - token: - type: string - # TODO: What is this actually? - description: A token. - example: "Hello World" - signatures: - type: object - title: Identity Server Signature - description: |- - The signature from the identity server. The `string` key - is the identity server's domain name, such as vector.im - additionalProperties: + requestBody: + content: + application/json: + schema: + type: object + properties: + medium: + type: string + description: |- + The type of third-party identifier. Currently only "email" is + a possible value. + example: email + address: + type: string + description: The third-party identifier itself. For example, an email address. + example: alice@example.com + mxid: + type: string + description: The user that is now bound to the third-party identifier. + example: "@alice:matrix.org" + invites: + type: array + description: A list of pending invites that the third-party identifier has + received. + items: + type: object + title: Third-party Invite + properties: + medium: + type: string + description: |- + The type of third-party invite issues. Currently only + "email" is used. + example: email + address: + type: string + description: The third-party identifier that received the invite. + example: alice@example.com + mxid: + type: string + description: The now-bound user ID that received the invite. + example: "@alice:matrix.org" + room_id: + type: string + description: The room ID the invite is valid for. + example: "!somewhere:example.org" + sender: + type: string + description: The user ID that sent the invite. + example: "@bob:matrix.org" + signed: + type: object + title: Identity Server Signatures + description: |- + Signature from the identity server using a long-term private + key. + properties: + mxid: + type: string + description: |- + The user ID that has been bound to the third-party + identifier. + example: "@alice:matrix.org" + token: + type: string + description: A token. + example: Hello World + signatures: type: object - title: Identity Server Domain Signature - description: The signature for the identity server. - properties: - "ed25519:0": - type: string - description: The signature. - example: "SomeSignatureGoesHere" - required: ['ed25519:0'] - example: { - "vector.im": { - "ed25519:0": "SomeSignatureGoesHere" - } - } - required: ['mxid', 'token', 'signatures'] - required: - - medium - - address - - mxid - - room_id - - sender - - signed - required: ['medium', 'address', 'mxid', 'invites'] + title: Identity Server Signature + description: |- + The signature from the identity server. The `string` key + is the identity server's domain name, such as vector.im + additionalProperties: + type: object + title: Identity Server Domain Signature + description: The signature for the identity server. + properties: + ed25519:0: + type: string + description: The signature. + example: SomeSignatureGoesHere + required: + - ed25519:0 + example: + vector.im: + ed25519:0: SomeSignatureGoesHere + required: + - mxid + - token + - signatures + required: + - medium + - address + - mxid + - room_id + - sender + - signed + required: + - medium + - address + - mxid + - invites + required: true responses: - 200: + "200": description: The homeserver has processed the notification. - examples: - application/json: {} - schema: - type: object - description: An empty object - example: {} + content: + application/json: + schema: + type: object + description: An empty object + example: {} + examples: + response: + value: {} +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/transactions.yaml b/data/api/server-server/transactions.yaml index d2aab20da..1ca2ed3c3 100644 --- a/data/api/server-server/transactions.yaml +++ b/data/api/server-server/transactions.yaml @@ -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 Federation Transaction API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation Transaction API + version: 1.0.0 paths: "/send/{txnId}": put: @@ -46,60 +35,80 @@ paths: parameters: - in: path name: txnId - type: string - description: |- - The transaction ID. - required: true - x-example: S0meTransacti0nId - - in: body - name: body - type: object + description: The transaction ID. required: true + example: S0meTransacti0nId schema: - allOf: - - $ref: "definitions/transaction.yaml" - - type: object - properties: - edus: - type: array - description: |- - List of ephemeral messages. May be omitted if there are no ephemeral - messages to be sent. Must not include more than 100 EDUs. - items: - $ref: "definitions/edu_with_example.yaml" + type: string + requestBody: + content: + application/json: + schema: + allOf: + - $ref: definitions/transaction.yaml + - type: object + properties: + edus: + type: array + description: |- + List of ephemeral messages. May be omitted if there are no ephemeral + messages to be sent. Must not include more than 100 EDUs. + items: + $ref: definitions/edu_with_example.yaml + type: object + required: true responses: - 200: + "200": description: |- The result of processing the transaction. The server is to use this response even in the event of one or more PDUs failing to be processed. - schema: - type: object - title: PDU Processing Results - description: The results for the processing of each PDU in the transaction. - properties: - pdus: + content: + application/json: + schema: type: object - description: |- - The PDUs from the original transaction. The string key represents the ID of the - PDU (event) that was processed. - additionalProperties: - type: object - title: PDU Processing Result - description: Information about how the PDU was handled. - properties: - error: - type: string - description: |- - A human readable description about what went wrong in processing this PDU. - If no error is present, the PDU can be considered successfully handled. - example: "You are not allowed to send a message to this room." - required: ['pdus'] - examples: - application/json: { - "pdus": { - "$successful_event:example.org": {}, - "$failed_event:example.org": { - "error": "You are not allowed to send a message to this room." - } - } - } + title: PDU Processing Results + description: The results for the processing of each PDU in the transaction. + properties: + pdus: + type: object + description: |- + The PDUs from the original transaction. The string key represents the ID of the + PDU (event) that was processed. + additionalProperties: + type: object + title: PDU Processing Result + description: Information about how the PDU was handled. + properties: + error: + type: string + description: |- + A human readable description about what went wrong in processing this PDU. + If no error is present, the PDU can be considered successfully handled. + example: You are not allowed to send a message to this room. + required: + - pdus + examples: + response: + value: { + "pdus": { + "$successful_event:example.org": {}, + "$failed_event:example.org": { + "error": "You are not allowed to send a message to this room." + } + } + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/user_devices.yaml b/data/api/server-server/user_devices.yaml index 142428671..a0022f56a 100644 --- a/data/api/server-server/user_devices.yaml +++ b/data/api/server-server/user_devices.yaml @@ -12,21 +12,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 Federation User Device Management API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation User Device Management API + version: 1.0.0 paths: "/user/devices/{userId}": get: @@ -38,80 +27,97 @@ paths: parameters: - in: path name: userId - type: string required: true description: |- The user ID to retrieve devices for. Must be a user local to the receiving homeserver. - x-example: "@alice:example.org" + example: "@alice:example.org" + schema: + type: string responses: - 200: + "200": description: The user's devices. - schema: - type: object - properties: - user_id: - type: string - description: The user ID devices were requested for. - example: "@alice:example.org" - stream_id: - type: integer - description: |- - A unique ID for a given user_id which describes the version of - the returned device list. This is matched with the `stream_id` - field in `m.device_list_update` EDUs in order to incrementally - update the returned device_list. - example: 5 - devices: - type: array - description: The user's devices. May be empty. - items: - type: object - title: User Device - properties: - device_id: - type: string - description: The device ID. - example: "JLAFKJWSCS" - keys: - type: object - description: Identity keys for the device. - allOf: - - $ref: "../client-server/definitions/device_keys.yaml" - device_display_name: - type: string - description: Optional display name for the device. - example: "Alice's Mobile Phone" - required: ['device_id', 'keys'] - master_key: + content: + application/json: + schema: type: object - description: |- - The user\'s master cross-signing key. - allOf: - - $ref: ../client-server/definitions/cross_signing_key.yaml - - example: { - "user_id": "@alice:example.com", - "usage": ["master"], - "keys": { - "ed25519:base64+master+public+key": "base64+master+public+key", - } - } - self_signing_key: - type: object - description: |- - The user\'s self-signing key. - allOf: - - $ref: ../client-server/definitions/cross_signing_key.yaml - - example: { - "user_id": "@alice:example.com", - "usage": ["self_signing"], - "keys": { - "ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key", - }, - "signatures": { - "@alice:example.com": { - "ed25519:base64+master+public+key": "signature+of+self+signing+key" - } - } - } - required: ['user_id', 'stream_id', 'devices'] + properties: + user_id: + type: string + description: The user ID devices were requested for. + example: "@alice:example.org" + stream_id: + type: integer + description: |- + A unique ID for a given user_id which describes the version of + the returned device list. This is matched with the `stream_id` + field in `m.device_list_update` EDUs in order to incrementally + update the returned device_list. + example: 5 + devices: + type: array + description: The user's devices. May be empty. + items: + type: object + title: User Device + properties: + device_id: + type: string + description: The device ID. + example: JLAFKJWSCS + keys: + type: object + description: Identity keys for the device. + allOf: + - $ref: ../client-server/definitions/device_keys.yaml + device_display_name: + type: string + description: Optional display name for the device. + example: Alice's Mobile Phone + required: + - device_id + - keys + master_key: + type: object + description: The user\'s master cross-signing key. + allOf: + - $ref: ../client-server/definitions/cross_signing_key.yaml + - example: + user_id: "@alice:example.com" + usage: + - master + keys: + ed25519:base64+master+public+key: base64+master+public+key + self_signing_key: + type: object + description: The user\'s self-signing key. + allOf: + - $ref: ../client-server/definitions/cross_signing_key.yaml + - example: + user_id: "@alice:example.com" + usage: + - self_signing + keys: + ed25519:base64+self+signing+public+key: base64+self+signing+master+public+key + signatures: + "@alice:example.com": + ed25519:base64+master+public+key: signature+of+self+signing+key + required: + - user_id + - stream_id + - devices +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/user_keys.yaml b/data/api/server-server/user_keys.yaml index fe84cbbdf..b823a31e0 100644 --- a/data/api/server-server/user_keys.yaml +++ b/data/api/server-server/user_keys.yaml @@ -12,246 +12,237 @@ # 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 Federation User Key Management API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -consumes: - - application/json -produces: - - application/json -securityDefinitions: - $ref: definitions/security.yaml + title: Matrix Federation User Key Management API + version: 1.0.0 paths: - "/user/keys/claim": + /user/keys/claim: post: summary: Claims one-time encryption keys for a user. - description: |- - Claims one-time keys for use in pre-key messages. + description: Claims one-time keys for use in pre-key messages. operationId: claimUserEncryptionKeys security: - signedRequest: [] - parameters: - - in: body - name: body - type: object - required: true - schema: - type: object - properties: - one_time_keys: - type: object - description: |- - The keys to be claimed. A map from user ID, to a map from - device ID to algorithm name. - additionalProperties: + requestBody: + content: + application/json: + schema: + type: object + properties: + one_time_keys: type: object + description: |- + The keys to be claimed. A map from user ID, to a map from + device ID to algorithm name. additionalProperties: - type: string - description: algorithm - example: "signed_curve25519" - example: { - "@alice:example.com": { - "JLAFKJWSCS": "signed_curve25519" - } - } - required: - - one_time_keys + type: object + additionalProperties: + type: string + description: algorithm + example: signed_curve25519 + example: + "@alice:example.com": + JLAFKJWSCS: signed_curve25519 + required: + - one_time_keys + required: true responses: - 200: + "200": description: The claimed keys. - schema: - type: object - properties: - one_time_keys: + content: + application/json: + schema: type: object - description: |- - One-time keys for the queried devices. A map from user ID, to a - map from devices to a map from `:` to the key object. - - See the [Client-Server Key Algorithms](/client-server-api/#key-algorithms) section for more information on - the Key Object format. - # User - additionalProperties: - type: object - # Device - additionalProperties: + properties: + one_time_keys: type: object - # Key + description: |- + One-time keys for the queried devices. A map from user ID, to a + map from devices to a map from `:` to the key object. + + See the [Client-Server Key Algorithms](/client-server-api/#key-algorithms) section for more information on + the Key Object format. additionalProperties: type: object - title: KeyObject - properties: - key: - type: string - description: The key, encoded using unpadded base64. - signatures: + additionalProperties: + type: object + additionalProperties: type: object - title: Signatures - additionalProperties: - type: object - additionalProperties: + title: KeyObject + properties: + key: type: string - description: |- - Signature of the key object. + description: The key, encoded using unpadded base64. + signatures: + type: object + title: Signatures + additionalProperties: + type: object + additionalProperties: + type: string + description: |- + Signature of the key object. - The signature is calculated using the process described at [Signing JSON](/appendices/#signing-json). - required: ['key', 'signatures'] - example: { - "@alice:example.com": { - "JLAFKJWSCS": { - "signed_curve25519:AAAAHg": { - "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs", - "signatures": { - "@alice:example.com": { - "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw" - } - } - } - } - } - } - required: ['one_time_keys'] - "/user/keys/query": + The signature is calculated using the process described at [Signing JSON](/appendices/#signing-json). + required: + - key + - signatures + example: + "@alice:example.com": + JLAFKJWSCS: + signed_curve25519:AAAAHg: + key: zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs + signatures: + "@alice:example.com": + ed25519:JLAFKJWSCS: FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw + required: + - one_time_keys + /user/keys/query: post: summary: Download device identity keys. - description: |- - Returns the current devices and identity keys for the given users. + description: Returns the current devices and identity keys for the given users. operationId: queryUserEncryptionKeys security: - signedRequest: [] - parameters: - - in: body - name: body - type: object - required: true - schema: - type: object - properties: - device_keys: - type: object - description: |- - The keys to be downloaded. A map from user ID, to a list of - device IDs, or to an empty list to indicate all devices for the - corresponding user. - additionalProperties: - type: array - items: - type: string - description: "Device ID" - example: { - "@alice:example.com": [] - } - required: ['device_keys'] + requestBody: + content: + application/json: + schema: + type: object + properties: + device_keys: + type: object + description: |- + The keys to be downloaded. A map from user ID, to a list of + device IDs, or to an empty list to indicate all devices for the + corresponding user. + additionalProperties: + type: array + items: + type: string + description: Device ID + example: + "@alice:example.com": [] + required: + - device_keys + required: true responses: - 200: + "200": description: The device information. - schema: - type: object - properties: - device_keys: + content: + application/json: + schema: type: object - description: |- - Information on the queried devices. A map from user ID, to a - map from device ID to device information. For each device, - the information returned will be the same as uploaded via - `/keys/upload`, with the addition of an `unsigned` - property. - additionalProperties: - type: object - additionalProperties: - allOf: - - $ref: ../client-server/definitions/device_keys.yaml - properties: - unsigned: - title: UnsignedDeviceInfo - type: object - description: |- - Additional data added to the device key information - by intermediate servers, and not covered by the - signatures. + properties: + device_keys: + type: object + description: |- + Information on the queried devices. A map from user ID, to a + map from device ID to device information. For each device, + the information returned will be the same as uploaded via + `/keys/upload`, with the addition of an `unsigned` + property. + additionalProperties: + type: object + additionalProperties: + allOf: + - $ref: ../client-server/definitions/device_keys.yaml properties: - device_display_name: - type: string - description: - The display name which the user set on the device. - master_keys: - x-addedInMatrixVersion: "1.1" - type: object - description: |- - Information on the master cross-signing keys of the queried users. - A map from user ID, to master key information. For each key, the - information returned will be the same as uploaded via - `/keys/device_signing/upload`, along with the signatures - uploaded via `/keys/signatures/upload` that the user is - allowed to see. - additionalProperties: - allOf: - - $ref: ../client-server/definitions/cross_signing_key.yaml - example: { - "@alice:example.com": { - "user_id": "@alice:example.com", - "usage": ["master"], - "keys": { - "ed25519:base64+master+public+key": "base64+master+public+key", - } - } - } - self_signing_keys: - x-addedInMatrixVersion: "1.1" - type: object - description: |- - Information on the self-signing keys of the queried users. A map - from user ID, to self-signing key information. For each key, the - information returned will be the same as uploaded via - `/keys/device_signing/upload`. - additionalProperties: - allOf: - - $ref: ../client-server/definitions/cross_signing_key.yaml - example: { - "@alice:example.com": { - "user_id": "@alice:example.com", - "usage": ["self_signing"], - "keys": { - "ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key", - }, - "signatures": { - "@alice:example.com": { - "ed25519:base64+master+public+key": "signature+of+self+signing+key" - } - } - } - } - required: ['device_keys'] - examples: - application/json: { - "device_keys": { - "@alice:example.com": { - "JLAFKJWSCS": { - "user_id": "@alice:example.com", - "device_id": "JLAFKJWSCS", - "algorithms": [ - "m.olm.v1.curve25519-aes-sha2", - "m.megolm.v1.aes-sha2" - ], - "keys": { - "curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI", - "ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI" - }, - "signatures": { + unsigned: + title: UnsignedDeviceInfo + type: object + description: |- + Additional data added to the device key information + by intermediate servers, and not covered by the + signatures. + properties: + device_display_name: + type: string + description: The display name which the user set on the device. + master_keys: + x-addedInMatrixVersion: "1.1" + type: object + description: |- + Information on the master cross-signing keys of the queried users. + A map from user ID, to master key information. For each key, the + information returned will be the same as uploaded via + `/keys/device_signing/upload`, along with the signatures + uploaded via `/keys/signatures/upload` that the user is + allowed to see. + additionalProperties: + allOf: + - $ref: ../client-server/definitions/cross_signing_key.yaml + example: + "@alice:example.com": + user_id: "@alice:example.com" + usage: + - master + keys: + ed25519:base64+master+public+key: base64+master+public+key + self_signing_keys: + x-addedInMatrixVersion: "1.1" + type: object + description: |- + Information on the self-signing keys of the queried users. A map + from user ID, to self-signing key information. For each key, the + information returned will be the same as uploaded via + `/keys/device_signing/upload`. + additionalProperties: + allOf: + - $ref: ../client-server/definitions/cross_signing_key.yaml + example: + "@alice:example.com": + user_id: "@alice:example.com" + usage: + - self_signing + keys: + ed25519:base64+self+signing+public+key: base64+self+signing+master+public+key + signatures: + "@alice:example.com": + ed25519:base64+master+public+key: signature+of+self+signing+key + required: + - device_keys + examples: + response: + value: { + "device_keys": { "@alice:example.com": { - "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA" + "JLAFKJWSCS": { + "user_id": "@alice:example.com", + "device_id": "JLAFKJWSCS", + "algorithms": [ + "m.olm.v1.curve25519-aes-sha2", + "m.megolm.v1.aes-sha2" + ], + "keys": { + "curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI", + "ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI" + }, + "signatures": { + "@alice:example.com": { + "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA" + } + }, + "unsigned": { + "device_display_name": "Alice's mobile phone" + } + } } - }, - "unsigned": { - "device_display_name": "Alice's mobile phone" } } - } - } - } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/version.yaml b/data/api/server-server/version.yaml index 929f7b91f..2ec59bf8e 100644 --- a/data/api/server-server/version.yaml +++ b/data/api/server-server/version.yaml @@ -11,44 +11,52 @@ # 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 Federation Version API" - version: "1.0.0" -host: localhost:8448 -schemes: - - https -basePath: /_matrix/federation/v1 -produces: - - application/json + title: Matrix Federation Version API + version: 1.0.0 paths: - "/version": + /version: get: summary: Get the implementation name and version of this homeserver. description: Get the implementation name and version of this homeserver. operationId: getVersion responses: - 200: - description: - The implementation name and version of this homeserver. - examples: - application/json: { - "server": { - "name": "My_Homeserver_Implementation", - "version": "ArbitraryVersionNumber" - } - } - schema: - type: object - properties: - server: - title: Server + "200": + description: The implementation name and version of this homeserver. + content: + application/json: + schema: type: object properties: - name: - type: string - description: Arbitrary name that identify this implementation. - version: - type: string - description: Version of this implementation. The version format depends on the implementation. + server: + title: Server + type: object + properties: + name: + type: string + description: Arbitrary name that identify this implementation. + version: + type: string + description: Version of this implementation. The version format depends on the + implementation. + examples: + response: + value: { + "server": { + "name": "My_Homeserver_Implementation", + "version": "ArbitraryVersionNumber" + } + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 diff --git a/data/api/server-server/wellknown.yaml b/data/api/server-server/wellknown.yaml index c1a060d98..717462f90 100644 --- a/data/api/server-server/wellknown.yaml +++ b/data/api/server-server/wellknown.yaml @@ -11,43 +11,53 @@ # 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 Federation Server Discovery API" - version: "1.0.0" -host: localhost:443 -schemes: - - https -basePath: /.well-known -produces: - - application/json + title: Matrix Federation Server Discovery API + version: 1.0.0 paths: - "/matrix/server": + /matrix/server: get: - summary: Gets information about the delegated server for server-server communication. + summary: Gets information about the delegated server for server-server + communication. description: |- Gets information about the delegated server for server-server communication between Matrix homeservers. Servers should follow 30x redirects, carefully avoiding redirect loops, and use normal X.509 certificate validation. operationId: getWellKnown responses: - 200: - description: - The delegated server information. The `Content-Type` for this response SHOULD - be `application/json`, however servers parsing the response should assume that - the body is JSON regardless of type. Failures parsing the JSON or invalid data - provided in the resulting parsed JSON should not result in discovery failure - - consult the server discovery process for information on how to continue. - examples: - application/json: { - "m.server": "delegated.example.com:1234" - } - schema: - type: object - properties: - "m.server": - type: string - description: |- - The server name to delegate server-server communications to, with optional - port. The delegated server name uses the same grammar as - [server names in the appendices](/appendices/#server-name). + "200": + description: The delegated server information. The `Content-Type` for this + response SHOULD be `application/json`, however servers parsing the + response should assume that the body is JSON regardless of type. + Failures parsing the JSON or invalid data provided in the resulting + parsed JSON should not result in discovery failure - consult the + server discovery process for information on how to continue. + content: + application/json: + schema: + type: object + properties: + m.server: + type: string + description: |- + The server name to delegate server-server communications to, with optional + port. The delegated server name uses the same grammar as + [server names in the appendices](/appendices/#server-name). + examples: + response: + value: { + "m.server": "delegated.example.com:1234" + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost + basePath: + default: /.well-known From c3a4f5b1098fc82b694559bfa053cac531a65062 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Tue, 9 May 2023 16:24:43 +0200 Subject: [PATCH 3/7] Manual fixes to API files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- .../appservice_room_directory.yaml | 3 + data/api/client-server/content-repo.yaml | 85 +++++-------------- .../client-server/definitions/push_rule.yaml | 6 +- data/api/client-server/device_management.yaml | 2 +- data/api/client-server/inviting.yaml | 2 + data/api/client-server/joining.yaml | 2 - data/api/client-server/keys.yaml | 11 +++ data/api/client-server/knocking.yaml | 2 - data/api/client-server/peeking_events.yaml | 2 + data/api/client-server/presence.yaml | 5 +- data/api/client-server/profile.yaml | 4 +- data/api/client-server/pusher.yaml | 3 +- data/api/client-server/pushrules.yaml | 4 +- data/api/client-server/receipts.yaml | 2 +- data/api/client-server/registration.yaml | 2 + data/api/client-server/relations.yaml | 8 ++ data/api/client-server/rooms.yaml | 3 + data/api/client-server/typing.yaml | 2 +- data/api/identity/v2_terms.yaml | 1 + data/api/push-gateway/push_notifier.yaml | 2 +- data/api/server-server/backfill.yaml | 2 - .../definitions/unsigned_pdu_base.yaml | 58 +++++++------ data/api/server-server/invites-v1.yaml | 16 ++++ data/api/server-server/invites-v2.yaml | 19 +++++ data/api/server-server/joins-v1.yaml | 20 +++-- data/api/server-server/joins-v2.yaml | 19 +++-- data/api/server-server/keys_query.yaml | 2 +- data/api/server-server/knocks.yaml | 17 +++- data/api/server-server/leaving-v1.yaml | 11 +++ data/api/server-server/leaving-v2.yaml | 12 +++ data/api/server-server/public_rooms.yaml | 1 + .../api/server-server/third_party_invite.yaml | 24 ++++++ data/api/server-server/user_keys.yaml | 3 + 33 files changed, 222 insertions(+), 133 deletions(-) diff --git a/data/api/client-server/appservice_room_directory.yaml b/data/api/client-server/appservice_room_directory.yaml index 98a819536..2af58a220 100644 --- a/data/api/client-server/appservice_room_directory.yaml +++ b/data/api/client-server/appservice_room_directory.yaml @@ -67,6 +67,7 @@ paths: - visibility required: true security: + # again, this is the appservice's token - not a typical client's - accessToken: [] responses: "200": @@ -94,4 +95,6 @@ servers: default: /_matrix/client/v3 components: securitySchemes: + # Note: this is the same access_token definition used elsewhere in the client + # server API, however this expects an access token for an application service. $ref: definitions/security.yaml diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml index c7e202e91..3678f782d 100644 --- a/data/api/client-server/content-repo.yaml +++ b/data/api/client-server/content-repo.yaml @@ -38,12 +38,7 @@ paths: type: string requestBody: content: - application/json: - schema: - type: string - example: - format: byte - "*/*": + application/octet-stream: schema: type: string example: @@ -146,12 +141,7 @@ paths: type: string requestBody: content: - application/json: - schema: - type: string - example: - format: byte - "*/*": + application/octet-stream: schema: type: string example: @@ -168,9 +158,6 @@ paths: examples: response: value: {} - "*/*": - schema: - type: object "403": description: |- The user does not have permission to upload the content. Some reasons for this error include: @@ -192,9 +179,6 @@ paths: "errcode": "M_FORBIDDEN", "error": "Cannot upload this content" } - "*/*": - schema: - $ref: definitions/errors/error.yaml "409": description: |- The endpoint was called with a media ID that already has content. A @@ -210,9 +194,6 @@ paths: "errcode": "M_CANNOT_OVERWRITE_MEDIA", "error": "Media already uploaded" } - "*/*": - schema: - $ref: definitions/errors/error.yaml "413": description: The uploaded content is too large for the server. content: @@ -225,18 +206,12 @@ paths: "errcode": "M_TOO_LARGE", "error": "Cannot upload files larger than 100mb" } - "*/*": - schema: - $ref: definitions/errors/error.yaml "429": description: This request was rate-limited. content: application/json: schema: $ref: definitions/errors/rate_limited.yaml - "*/*": - schema: - $ref: definitions/errors/rate_limited.yaml tags: - Media /media/v1/create: @@ -266,6 +241,8 @@ paths: x-addedInMatrixVersion: "1.7" security: - accessToken: [] + # empty json object + parameters: [] responses: "200": description: The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) for @@ -371,24 +348,23 @@ paths: schema: type: string content: - "*/*": + application/octet-stream: schema: type: string + # This is a workaround for us not being able to say the response is required. description: "**Required.** The bytes for the uploaded file." - format: binary "429": description: This request was rate-limited. content: - "*/*": + application/json: schema: $ref: definitions/errors/rate_limited.yaml "502": description: The content is too large for the server to serve. content: - "*/*": + application/json: schema: $ref: definitions/errors/error.yaml - application/json: examples: response: value: { @@ -400,10 +376,9 @@ paths: The content is not yet available. A [standard error response](/client-server-api/#standard-error-response) will be returned with the `errcode` `M_NOT_YET_UPLOADED`. content: - "*/*": + application/json: schema: $ref: definitions/errors/error.yaml - application/json: examples: response: value: { @@ -485,24 +460,24 @@ paths: schema: type: string content: - "*/*": + application/octet-stream: schema: type: string + # This is a workaround for us not being able to say the response is required. description: "**Required.** The bytes for the uploaded file." format: binary "429": description: This request was rate-limited. content: - "*/*": + application/json: schema: $ref: definitions/errors/rate_limited.yaml "502": description: The content is too large for the server to serve. content: - "*/*": + application/json: schema: $ref: definitions/errors/error.yaml - application/json: examples: response: value: { @@ -514,10 +489,9 @@ paths: The content is not yet available. A [standard error response](/client-server-api/#standard-error-response) will be returned with the `errcode` `M_NOT_YET_UPLOADED`. content: - "*/*": + application/json: schema: $ref: definitions/errors/error.yaml - application/json: examples: response: value: { @@ -620,11 +594,13 @@ paths: image/jpeg: schema: type: string + # This is a workaround for us not being able to say the response is required. description: "**Required.** The bytes for the thumbnail." format: binary image/png: schema: type: string + # This is a workaround for us not being able to say the response is required. description: "**Required.** The bytes for the thumbnail." format: binary "400": @@ -633,13 +609,9 @@ paths: the content. For example, the client requested non-integer dimensions or asked for negatively-sized images. content: - image/jpeg: - schema: - $ref: definitions/errors/error.yaml - image/png: + application/json: schema: $ref: definitions/errors/error.yaml - application/json: examples: response: value: { @@ -649,13 +621,9 @@ paths: "413": description: The local content is too large for the server to thumbnail. content: - image/jpeg: - schema: - $ref: definitions/errors/error.yaml - image/png: + application/json: schema: $ref: definitions/errors/error.yaml - application/json: examples: response: value: { @@ -665,22 +633,15 @@ paths: "429": description: This request was rate-limited. content: - image/jpeg: - schema: - $ref: definitions/errors/rate_limited.yaml - image/png: + application/json: schema: $ref: definitions/errors/rate_limited.yaml "502": description: The remote content is too large for the server to thumbnail. content: - image/jpeg: - schema: - $ref: definitions/errors/error.yaml - image/png: + application/json: schema: $ref: definitions/errors/error.yaml - application/json: examples: response: value: { @@ -692,13 +653,9 @@ paths: The content is not yet available. A [standard error response](/client-server-api/#standard-error-response) will be returned with the `errcode` `M_NOT_YET_UPLOADED`. content: - image/jpeg: - schema: - $ref: definitions/errors/error.yaml - image/png: + application/json: schema: $ref: definitions/errors/error.yaml - application/json: examples: response: value: { diff --git a/data/api/client-server/definitions/push_rule.yaml b/data/api/client-server/definitions/push_rule.yaml index 94a9d320b..4f1b41adb 100644 --- a/data/api/client-server/definitions/push_rule.yaml +++ b/data/api/client-server/definitions/push_rule.yaml @@ -17,9 +17,9 @@ type: object properties: actions: items: - type: - - object - - string + oneOf: + - type: object + - type: string type: array description: |- The actions to perform when this rule is matched. diff --git a/data/api/client-server/device_management.yaml b/data/api/client-server/device_management.yaml index 9ae3f5578..32d3db9ac 100644 --- a/data/api/client-server/device_management.yaml +++ b/data/api/client-server/device_management.yaml @@ -124,7 +124,7 @@ paths: content: application/json: schema: - type: object + type: object # empty json object examples: response: value: {} diff --git a/data/api/client-server/inviting.yaml b/data/api/client-server/inviting.yaml index 4c373c777..ce5d503da 100644 --- a/data/api/client-server/inviting.yaml +++ b/data/api/client-server/inviting.yaml @@ -16,6 +16,8 @@ info: title: Matrix Client-Server Room Joining API version: 1.0.0 paths: + # With an extra " " to disambiguate from the 3pid invite endpoint + # The extra space makes it sort first for what I'm sure is a good reason. "/rooms/{roomId}/invite ": post: summary: Invite a user to participate in a particular room. diff --git a/data/api/client-server/joining.yaml b/data/api/client-server/joining.yaml index 35f56cac9..020c5a0e8 100644 --- a/data/api/client-server/joining.yaml +++ b/data/api/client-server/joining.yaml @@ -143,8 +143,6 @@ paths: example: - matrix.org - elsewhere.ca - style: form - explode: false schema: type: array items: diff --git a/data/api/client-server/keys.yaml b/data/api/client-server/keys.yaml index 3f6bc8060..cb8a11dbb 100644 --- a/data/api/client-server/keys.yaml +++ b/data/api/client-server/keys.yaml @@ -38,6 +38,10 @@ paths: allOf: - $ref: definitions/device_keys.yaml one_time_keys: + # $ref: "definitions/one_time_keys.yaml" + # XXX: We can't define an actual object here, so we have to hope + # that people will look at the swagger source or can figure it out + # from the other endpoints/example. type: object title: OneTimeKeys description: |- @@ -61,6 +65,8 @@ paths: ed25519:JLAFKJWSCS: IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA fallback_keys: x-addedInMatrixVersion: "1.2" + # $ref: "definitions/one_time_keys.yaml" + # XXX: We can't define an actual object here - see above. type: object title: OneTimeKeys description: |- @@ -346,6 +352,11 @@ paths: additionalProperties: type: object additionalProperties: + # $ref: "definitions/one_time_keys.yaml" + # XXX: We can't define an actual object here, so we have to hope + # that people will read the link provided in the description + # and figure it out from the other endpoints/example. + # See also one_time_key parameter for /keys/upload above. type: object title: OneTimeKeys example: diff --git a/data/api/client-server/knocking.yaml b/data/api/client-server/knocking.yaml index f8f16b486..b778f02b6 100644 --- a/data/api/client-server/knocking.yaml +++ b/data/api/client-server/knocking.yaml @@ -55,8 +55,6 @@ paths: example: - matrix.org - elsewhere.ca - style: form - explode: false schema: type: array items: diff --git a/data/api/client-server/peeking_events.yaml b/data/api/client-server/peeking_events.yaml index 6ed44b790..19eb67a02 100644 --- a/data/api/client-server/peeking_events.yaml +++ b/data/api/client-server/peeking_events.yaml @@ -16,6 +16,8 @@ info: title: Matrix Client-Server Sync Guest API version: 1.0.0 paths: + # With an extra " " to disambiguate from the getEvents endpoint + # The extra space makes it sort first for what I'm sure is a good reason. "/events ": get: summary: Listen on the event stream of a particular room. diff --git a/data/api/client-server/presence.yaml b/data/api/client-server/presence.yaml index 4deda9e03..caa198543 100644 --- a/data/api/client-server/presence.yaml +++ b/data/api/client-server/presence.yaml @@ -65,7 +65,7 @@ paths: content: application/json: schema: - type: object + type: object # empty json object examples: response: value: {} @@ -113,8 +113,7 @@ paths: by this user. status_msg: description: The state message for this user if one was set. - nullable: true - type: string + type: ["string", "null"] currently_active: type: boolean description: Whether the user is currently active diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml index 17d0d1b9b..b47cf591f 100644 --- a/data/api/client-server/profile.yaml +++ b/data/api/client-server/profile.yaml @@ -53,7 +53,7 @@ paths: content: application/json: schema: - type: object + type: object # empty json object examples: response: value: {} @@ -139,7 +139,7 @@ paths: content: application/json: schema: - type: object + type: object # empty json object examples: response: value: {} diff --git a/data/api/client-server/pusher.yaml b/data/api/client-server/pusher.yaml index 101104754..c686e9aeb 100644 --- a/data/api/client-server/pusher.yaml +++ b/data/api/client-server/pusher.yaml @@ -174,8 +174,7 @@ paths: The kind of pusher to configure. `"http"` makes a pusher that sends HTTP pokes. `"email"` makes a pusher that emails the user with unread notifications. `null` deletes the pusher. - nullable: true - type: string + type: ["string", "null"] app_id: type: string description: |- diff --git a/data/api/client-server/pushrules.yaml b/data/api/client-server/pushrules.yaml index 32812a2a1..77a07afd6 100644 --- a/data/api/client-server/pushrules.yaml +++ b/data/api/client-server/pushrules.yaml @@ -350,7 +350,7 @@ paths: content: application/json: schema: - type: object + type: object # empty json object examples: response: value: {} @@ -487,7 +487,7 @@ paths: content: application/json: schema: - type: object + type: object # empty json object examples: response: value: {} diff --git a/data/api/client-server/receipts.yaml b/data/api/client-server/receipts.yaml index 279cdda1a..abbd7a62c 100644 --- a/data/api/client-server/receipts.yaml +++ b/data/api/client-server/receipts.yaml @@ -89,7 +89,7 @@ paths: application/json: schema: type: object - maxProperties: 0 + maxProperties: 0 # empty json object examples: response: value: {} diff --git a/data/api/client-server/registration.yaml b/data/api/client-server/registration.yaml index d961ac177..1f823ac84 100644 --- a/data/api/client-server/registration.yaml +++ b/data/api/client-server/registration.yaml @@ -66,6 +66,8 @@ paths: name: kind required: false description: The kind of account to register. Defaults to `user`. + # swagger-UI overrides the default with the example, so better make the + # example the default. example: user schema: type: string diff --git a/data/api/client-server/relations.yaml b/data/api/client-server/relations.yaml index f773c39b6..65c3491ad 100644 --- a/data/api/client-server/relations.yaml +++ b/data/api/client-server/relations.yaml @@ -97,6 +97,8 @@ paths: - b - f responses: + # note: this endpoint deliberately does not support rate limiting, therefore a + # 429 error response is not included. "200": description: |- The paginated child events which point to the parent. If no events are @@ -161,6 +163,7 @@ paths: } tags: - Event relationships + # The same as above, with added `/{relType}` "/rooms/{roomId}/relations/{eventId}/{relType}": get: summary: Get the child events for a given parent event, with a given `relType`. @@ -251,6 +254,8 @@ paths: - b - f responses: + # note: this endpoint deliberately does not support rate limiting, therefore a + # 429 error response is not included. "200": description: |- The paginated child events which point to the parent. If no events are @@ -317,6 +322,7 @@ paths: } tags: - Event relationships + # The same as above, with added `/{eventType}` "/rooms/{roomId}/relations/{eventId}/{relType}/{eventType}": get: summary: Get the child events for a given parent event, with a given `relType` @@ -419,6 +425,8 @@ paths: - b - f responses: + # note: this endpoint deliberately does not support rate limiting, therefore a + # 429 error response is not included. "200": description: |- The paginated child events which point to the parent. If no events are diff --git a/data/api/client-server/rooms.yaml b/data/api/client-server/rooms.yaml index 15a0fea12..4a192305c 100644 --- a/data/api/client-server/rooms.yaml +++ b/data/api/client-server/rooms.yaml @@ -200,6 +200,9 @@ paths: example: YWxsCgpOb25lLDM1ODcwOA schema: type: string + # XXX: As mentioned in MSC1227, replacing `[not_]membership` with a JSON + # filter might be a better alternative. + # See https://github.com/matrix-org/matrix-doc/issues/1337 - in: query name: membership description: |- diff --git a/data/api/client-server/typing.yaml b/data/api/client-server/typing.yaml index 4e53cf69c..6d6a7437c 100644 --- a/data/api/client-server/typing.yaml +++ b/data/api/client-server/typing.yaml @@ -70,7 +70,7 @@ paths: content: application/json: schema: - type: object + type: object # empty json object examples: response: value: {} diff --git a/data/api/identity/v2_terms.yaml b/data/api/identity/v2_terms.yaml index 035688823..f4a459324 100644 --- a/data/api/identity/v2_terms.yaml +++ b/data/api/identity/v2_terms.yaml @@ -52,6 +52,7 @@ paths: might be and could be "alpha", semantically versioned, or arbitrary. required: - version + # TODO: TravisR - Make this render additionalProperties: type: object title: Internationalised Policy diff --git a/data/api/push-gateway/push_notifier.yaml b/data/api/push-gateway/push_notifier.yaml index c64011d25..e23d33b0b 100644 --- a/data/api/push-gateway/push_notifier.yaml +++ b/data/api/push-gateway/push_notifier.yaml @@ -202,7 +202,7 @@ paths: content: application/json: schema: - type: object + type: object # empty json object properties: rejected: type: array diff --git a/data/api/server-server/backfill.yaml b/data/api/server-server/backfill.yaml index 9d82edc72..a37e5ed45 100644 --- a/data/api/server-server/backfill.yaml +++ b/data/api/server-server/backfill.yaml @@ -40,8 +40,6 @@ paths: required: true example: - $abc123:matrix.org - style: form - explode: false schema: type: array items: diff --git a/data/api/server-server/definitions/unsigned_pdu_base.yaml b/data/api/server-server/definitions/unsigned_pdu_base.yaml index 20a3e83d7..c21149f67 100644 --- a/data/api/server-server/definitions/unsigned_pdu_base.yaml +++ b/data/api/server-server/definitions/unsigned_pdu_base.yaml @@ -56,20 +56,21 @@ properties: maxItems: 2 minItems: 2 items: - - type: string - title: Event ID - example: "$abc123:matrix.org" - - type: object - title: Event Hash - example: { - "sha256": "Base64EncodedSha256HashesShouldBe43BytesLong" - } - properties: - sha256: - type: string - description: The event hash. - example: Base64EncodedSha256HashesShouldBe43BytesLong - required: ['sha256'] + anyOf: + - type: string + title: Event ID + example: "$abc123:matrix.org" + - type: object + title: Event Hash + example: { + "sha256": "Base64EncodedSha256HashesShouldBe43BytesLong" + } + properties: + sha256: + type: string + description: The event hash. + example: Base64EncodedSha256HashesShouldBe43BytesLong + required: ['sha256'] depth: type: integer description: |- @@ -91,20 +92,21 @@ properties: maxItems: 2 minItems: 2 items: - - type: string - title: Event ID - example: "$abc123:matrix.org" - - type: object - title: Event Hash - example: { - "sha256": "Base64EncodedSha256HashesShouldBe43BytesLong" - } - properties: - sha256: - type: string - description: The event hash. - example: Base64EncodedSha256HashesShouldBe43BytesLong - required: ['sha256'] + anyOf: + - type: string + title: Event ID + example: "$abc123:matrix.org" + - type: object + title: Event Hash + example: { + "sha256": "Base64EncodedSha256HashesShouldBe43BytesLong" + } + properties: + sha256: + type: string + description: The event hash. + example: Base64EncodedSha256HashesShouldBe43BytesLong + required: ['sha256'] redacts: type: string description: For redaction events, the ID of the event being redacted. diff --git a/data/api/server-server/invites-v1.yaml b/data/api/server-server/invites-v1.yaml index 78a24b498..270682d9f 100644 --- a/data/api/server-server/invites-v1.yaml +++ b/data/api/server-server/invites-v1.yaml @@ -75,6 +75,22 @@ paths: example: $ref: ../../event-schemas/examples/invite_room_state.json type: object + example: { + "room_id": "!somewhere:example.org", + "type": "m.room.member", + "state_key": "@joe:elsewhere.com", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "invite" + }, + "signatures": { + "example.com": { + "ed25519:key_version": "SomeSignatureHere" + }, + } + } required: true responses: "200": diff --git a/data/api/server-server/invites-v2.yaml b/data/api/server-server/invites-v2.yaml index 5006a1882..91dfca3ab 100644 --- a/data/api/server-server/invites-v2.yaml +++ b/data/api/server-server/invites-v2.yaml @@ -78,6 +78,25 @@ paths: required: - room_version - event + example: { + "room_version": "2", + "event": { + "room_id": "!somewhere:example.org", + "type": "m.room.member", + "state_key": "@joe:elsewhere.com", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "invite" + }, + "signatures": { + "example.com": { + "ed25519:key_version": "SomeSignatureHere" + }, + } + } + } required: true responses: "200": diff --git a/data/api/server-server/joins-v1.yaml b/data/api/server-server/joins-v1.yaml index 016381522..35b20e616 100644 --- a/data/api/server-server/joins-v1.yaml +++ b/data/api/server-server/joins-v1.yaml @@ -49,8 +49,6 @@ paths: example: - "1" - "2" - style: form - explode: false schema: type: array items: @@ -321,6 +319,18 @@ paths: - origin_server_ts - type - content + example: { + "room_id": "!somewhere:example.org", + "type": "m.room.member", + "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "join", + "join_authorised_via_users_server": "@anyone:resident.example.org" + } + } required: true responses: "200": @@ -356,9 +366,6 @@ paths: description: |- The [PDUs](/server-server-api/#pdus) that make up the auth chain. The event format varies depending on the room version - check the [room version specification](/rooms) for precise event formats. - schema: - type: object - properties: {} state: type: array description: |- @@ -372,9 +379,6 @@ paths: description: |- The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format varies depending on the room version - check the [room version specification](/rooms) for precise event formats. - schema: - type: object - properties: {} required: - auth_chain - state diff --git a/data/api/server-server/joins-v2.yaml b/data/api/server-server/joins-v2.yaml index d4f26cca2..32819193b 100644 --- a/data/api/server-server/joins-v2.yaml +++ b/data/api/server-server/joins-v2.yaml @@ -17,6 +17,7 @@ info: title: Matrix Federation Join Room API version: 1.0.0 paths: + # Note: there is no v2 of make_join (yet) "/send_join/{roomId}/{eventId}": put: summary: Submit a signed join event to a resident server @@ -138,6 +139,18 @@ paths: - origin_server_ts - type - content + example: { + "room_id": "!somewhere:example.org", + "type": "m.room.member", + "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "join", + "join_authorised_via_users_server": "@anyone:resident.example.org" + } + } required: true responses: "200": @@ -171,9 +184,6 @@ paths: items: type: object title: PDU - schema: - type: object - properties: {} x-changedInMatrixVersion: "1.6": |- reworded to include only consider state events returned in @@ -190,9 +200,6 @@ paths: items: type: object title: PDU - schema: - type: object - properties: {} x-changedInMatrixVersion: "1.6": permit omission of membership events. event: diff --git a/data/api/server-server/keys_query.yaml b/data/api/server-server/keys_query.yaml index b639a2a84..096cc5a61 100644 --- a/data/api/server-server/keys_query.yaml +++ b/data/api/server-server/keys_query.yaml @@ -88,7 +88,7 @@ paths: given. additionalProperties: type: object - name: ServerName + title: ServerName description: The server names to query. additionalProperties: type: object diff --git a/data/api/server-server/knocks.yaml b/data/api/server-server/knocks.yaml index bab56d95a..266e33683 100644 --- a/data/api/server-server/knocks.yaml +++ b/data/api/server-server/knocks.yaml @@ -44,12 +44,10 @@ paths: - in: query name: ver description: The room versions the sending server has support for. - required: true + required: true # knocking was supported in v7 example: - "1" - "7" - style: form - explode: false schema: type: array items: @@ -121,7 +119,7 @@ paths: - content - sender required: - - room_version + - room_version # knocking was added in v7 - event examples: response: @@ -273,6 +271,17 @@ paths: - origin_server_ts - type - content + example: { + "room_id": "!somewhere:example.org", + "type": "m.room.member", + "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "knock" + } + } required: true responses: "200": diff --git a/data/api/server-server/leaving-v1.yaml b/data/api/server-server/leaving-v1.yaml index c339cc033..a6c829872 100644 --- a/data/api/server-server/leaving-v1.yaml +++ b/data/api/server-server/leaving-v1.yaml @@ -222,6 +222,17 @@ paths: - type - depth - content + example: { + "room_id": "!somewhere:example.org", + "type": "m.room.member", + "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "leave" + } + } required: true responses: "200": diff --git a/data/api/server-server/leaving-v2.yaml b/data/api/server-server/leaving-v2.yaml index 6701c7c1f..75248b535 100644 --- a/data/api/server-server/leaving-v2.yaml +++ b/data/api/server-server/leaving-v2.yaml @@ -17,6 +17,7 @@ info: title: Matrix Federation Leave Room API version: 1.0.0 paths: + # Note: there is no v2 of make_leave (yet) "/send_leave/{roomId}/{eventId}": put: summary: Submit a signed leave event to a resident server @@ -107,6 +108,17 @@ paths: - type - depth - content + example: { + "room_id": "!somewhere:example.org", + "type": "m.room.member", + "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "leave" + } + } required: true responses: "200": diff --git a/data/api/server-server/public_rooms.yaml b/data/api/server-server/public_rooms.yaml index 4e0c7a1f7..dd909f8f1 100644 --- a/data/api/server-server/public_rooms.yaml +++ b/data/api/server-server/public_rooms.yaml @@ -159,6 +159,7 @@ paths: - $ref: ../client-server/definitions/public_rooms_chunk.yaml - type: object properties: + # Override description of join_rule join_rule: type: string description: |- diff --git a/data/api/server-server/third_party_invite.yaml b/data/api/server-server/third_party_invite.yaml index ff8ba3cab..3eac4811d 100644 --- a/data/api/server-server/third_party_invite.yaml +++ b/data/api/server-server/third_party_invite.yaml @@ -151,6 +151,27 @@ paths: - sender - state_key - content + example: { + "type": "m.room.member", + "room_id": "!abc123:matrix.org", + "sender": "@joe:matrix.org", + "state_key": "@someone:example.org", + "content": { + "membership": "invite", + "third_party_invite": { + "display_name": "alice", + "signed": { + "mxid": "@alice:localhost", + "token": "abc123", + "signatures": { + "magic.forest": { + "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" + } + } + } + } + } + } description: A partial `m.room.member` event required: true responses: @@ -225,6 +246,8 @@ paths: type: string description: The user ID that sent the invite. example: "@bob:matrix.org" + # TODO (TravisR): Make this reusable when doing IS spec changes + # also make sure it isn't lying about anything, like the key version signed: type: object title: Identity Server Signatures @@ -240,6 +263,7 @@ paths: example: "@alice:matrix.org" token: type: string + # TODO: What is this actually? description: A token. example: Hello World signatures: diff --git a/data/api/server-server/user_keys.yaml b/data/api/server-server/user_keys.yaml index b823a31e0..60995a748 100644 --- a/data/api/server-server/user_keys.yaml +++ b/data/api/server-server/user_keys.yaml @@ -63,10 +63,13 @@ paths: See the [Client-Server Key Algorithms](/client-server-api/#key-algorithms) section for more information on the Key Object format. + # User additionalProperties: type: object + # Device additionalProperties: type: object + # Key additionalProperties: type: object title: KeyObject From 4fafc987738e8f8e068453e453e290b671569af8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Tue, 9 May 2023 16:26:25 +0200 Subject: [PATCH 4/7] Update scripts for OpenAPI 3.1 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- scripts/dump-swagger.py | 22 +-- scripts/package-lock.json | 298 +++++++++++++++++++++----------------- scripts/package.json | 4 +- scripts/validator.js | 16 +- 4 files changed, 189 insertions(+), 151 deletions(-) diff --git a/scripts/dump-swagger.py b/scripts/dump-swagger.py index 82de87631..ce97c4c3c 100755 --- a/scripts/dump-swagger.py +++ b/scripts/dump-swagger.py @@ -133,16 +133,15 @@ def edit_links(node, base_url): logging.basicConfig() output = { - "basePath": "/", - "consumes": ["application/json"], - "produces": ["application/json"], - "host": "matrix.org", # The servers value will be picked up by RapiDoc to provide a way # to switch API servers. Useful when one wants to test compliance # of their server with the API. "servers": [ { - "url": "https://{homeserver_address}/", + "url": "https://matrix.org", + }, + { + "url": "https://{homeserver_address}", "variables": { "homeserver_address": { "default": "matrix-client.matrix.org", @@ -151,20 +150,21 @@ def edit_links(node, base_url): }, } ], - "schemes": ["https"], "info": { "title": available_apis[selected_api], "version": release_label, }, - "securityDefinitions": {}, + "components": { + "securitySchemes": {} + }, "paths": {}, - "swagger": "2.0", + "openapi": "3.1.0", } selected_api_dir = os.path.join(api_dir, selected_api) try: with open(os.path.join(selected_api_dir, 'definitions', 'security.yaml')) as f: - output['securityDefinitions'] = yaml.safe_load(f) + output['components']['securitySchemes'] = yaml.safe_load(f) except FileNotFoundError: print("No security definitions available for this API") @@ -174,12 +174,12 @@ def edit_links(node, base_url): continue filepath = os.path.join(selected_api_dir, filename) - print("Reading swagger API: %s" % filepath) + print("Reading OpenAPI: %s" % filepath) with open(filepath, "r") as f: api = yaml.safe_load(f.read()) api = resolve_references(filepath, api) - basePath = api['basePath'] + basePath = api['servers'][0]['variables']['basePath']['default'] for path, methods in api["paths"].items(): path = basePath + path for method, spec in methods.items(): diff --git a/scripts/package-lock.json b/scripts/package-lock.json index 5e3937c26..6b6e53287 100644 --- a/scripts/package-lock.json +++ b/scripts/package-lock.json @@ -9,19 +9,18 @@ "version": "0.0.1", "license": "ISC", "dependencies": { - "nopt": "^3.0.2", - "swagger-parser": "^10.0.3" + "@apidevtools/swagger-parser": "^10.1.0", + "nopt": "^3.0.2" } }, "node_modules/@apidevtools/json-schema-ref-parser": { - "version": "9.0.9", - "resolved": "https://registry.npmjs.org/@apidevtools/json-schema-ref-parser/-/json-schema-ref-parser-9.0.9.tgz", - "integrity": "sha512-GBD2Le9w2+lVFoc4vswGI/TjkNIZSVp7+9xPf+X3uidBfWnAeUWmquteSyt0+VCrhNMWj/FTABISQrD3Z/YA+w==", + "version": "9.0.6", + "resolved": "https://registry.npmjs.org/@apidevtools/json-schema-ref-parser/-/json-schema-ref-parser-9.0.6.tgz", + "integrity": "sha512-M3YgsLjI0lZxvrpeGVk9Ap032W6TPQkH6pRAZz81Ac3WUNF79VQooAFnp8umjvVzUmD93NkogxEwbSce7qMsUg==", "dependencies": { "@jsdevtools/ono": "^7.1.3", - "@types/json-schema": "^7.0.6", "call-me-maybe": "^1.0.1", - "js-yaml": "^4.1.0" + "js-yaml": "^3.13.1" } }, "node_modules/@apidevtools/openapi-schemas": { @@ -38,16 +37,17 @@ "integrity": "sha512-QAkD5kK2b1WfjDS/UQn/qQkbwF31uqRjPTrsCs5ZG9BQGAkjwvqGFjjPqAuzac/IYzpPtRzjCP1WrTuAIjMrXg==" }, "node_modules/@apidevtools/swagger-parser": { - "version": "10.0.3", - "resolved": "https://registry.npmjs.org/@apidevtools/swagger-parser/-/swagger-parser-10.0.3.tgz", - "integrity": "sha512-sNiLY51vZOmSPFZA5TF35KZ2HbgYklQnTSDnkghamzLb3EkNtcQnrBQEj5AOCxHpTtXpqMCRM1CrmV2rG6nw4g==", + "version": "10.1.0", + "resolved": "https://registry.npmjs.org/@apidevtools/swagger-parser/-/swagger-parser-10.1.0.tgz", + "integrity": "sha512-9Kt7EuS/7WbMAUv2gSziqjvxwDbFSg3Xeyfuj5laUODX8o/k/CpsAKiQ8W7/R88eXFTMbJYg6+7uAmOWNKmwnw==", "dependencies": { - "@apidevtools/json-schema-ref-parser": "^9.0.6", - "@apidevtools/openapi-schemas": "^2.0.4", + "@apidevtools/json-schema-ref-parser": "9.0.6", + "@apidevtools/openapi-schemas": "^2.1.0", "@apidevtools/swagger-methods": "^3.0.2", "@jsdevtools/ono": "^7.1.3", - "call-me-maybe": "^1.0.1", - "z-schema": "^5.0.1" + "ajv": "^8.6.3", + "ajv-draft-04": "^1.0.0", + "call-me-maybe": "^1.0.1" }, "peerDependencies": { "openapi-types": ">=7" @@ -58,52 +58,85 @@ "resolved": "https://registry.npmjs.org/@jsdevtools/ono/-/ono-7.1.3.tgz", "integrity": "sha512-4JQNk+3mVzK3xh2rqd6RB4J46qUR19azEHBneZyTZM+c456qOrbbM/5xcR8huNCCcbVt7+UmizG6GuUvPvKUYg==" }, - "node_modules/@types/json-schema": { - "version": "7.0.9", - "resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.9.tgz", - "integrity": "sha512-qcUXuemtEu+E5wZSJHNxUXeCZhAfXKQ41D+duX+VYPde7xyEVZci+/oXKJL13tnRs9lR2pr4fod59GT6/X1/yQ==" - }, "node_modules/abbrev": { "version": "1.1.1", "resolved": "https://registry.npmjs.org/abbrev/-/abbrev-1.1.1.tgz", "integrity": "sha512-nne9/IiQ/hzIhY6pdDnbBtz7DjPTKrY00P/zvPSm5pOFkl6xuGrGnXn/VtTNNfNtAfZ9/1RtehkszU9qcTii0Q==" }, + "node_modules/ajv": { + "version": "8.11.0", + "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.11.0.tgz", + "integrity": "sha512-wGgprdCvMalC0BztXvitD2hC04YffAvtsUn93JbGXYLAtCUO4xd17mCCZQxUOItiBwZvJScWo8NIvQMQ71rdpg==", + "dependencies": { + "fast-deep-equal": "^3.1.1", + "json-schema-traverse": "^1.0.0", + "require-from-string": "^2.0.2", + "uri-js": "^4.2.2" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/epoberezkin" + } + }, + "node_modules/ajv-draft-04": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/ajv-draft-04/-/ajv-draft-04-1.0.0.tgz", + "integrity": "sha512-mv00Te6nmYbRp5DCwclxtt7yV/joXJPGS7nM+97GdxvuttCOfgI3K4U25zboyeX0O+myI8ERluxQe5wljMmVIw==", + "peerDependencies": { + "ajv": "^8.5.0" + }, + "peerDependenciesMeta": { + "ajv": { + "optional": true + } + } + }, "node_modules/argparse": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", - "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==" + "version": "1.0.10", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz", + "integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==", + "dependencies": { + "sprintf-js": "~1.0.2" + } }, "node_modules/call-me-maybe": { "version": "1.0.1", "resolved": "https://registry.npmjs.org/call-me-maybe/-/call-me-maybe-1.0.1.tgz", - "integrity": "sha1-JtII6onje1y95gJQoV8DHBak1ms=" + "integrity": "sha512-wCyFsDQkKPwwF8BDwOiWNx/9K45L/hvggQiDbve+viMNMQnWhrlYIuBk09offfwCRtCO9P6XwUttufzU11WCVw==" + }, + "node_modules/esprima": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz", + "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==", + "bin": { + "esparse": "bin/esparse.js", + "esvalidate": "bin/esvalidate.js" + }, + "engines": { + "node": ">=4" + } }, - "node_modules/commander": { - "version": "2.20.3", - "resolved": "https://registry.npmjs.org/commander/-/commander-2.20.3.tgz", - "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==", - "optional": true + "node_modules/fast-deep-equal": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz", + "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==" }, "node_modules/js-yaml": { - "version": "4.1.0", - "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz", - "integrity": "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==", + "version": "3.14.1", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.14.1.tgz", + "integrity": "sha512-okMH7OXXJ7YrN9Ok3/SXrnu4iX9yOk+25nqX4imS2npuvTYDmo/QEZoqwZkYaIDk3jVvBOTOIEgEhaLOynBS9g==", "dependencies": { - "argparse": "^2.0.1" + "argparse": "^1.0.7", + "esprima": "^4.0.0" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, - "node_modules/lodash.get": { - "version": "4.4.2", - "resolved": "https://registry.npmjs.org/lodash.get/-/lodash.get-4.4.2.tgz", - "integrity": "sha1-LRd/ZS+jHpObRDjVNBSZ36OCXpk=" - }, - "node_modules/lodash.isequal": { - "version": "4.5.0", - "resolved": "https://registry.npmjs.org/lodash.isequal/-/lodash.isequal-4.5.0.tgz", - "integrity": "sha1-QVxEePK8wwEgwizhDtMib30+GOA=" + "node_modules/json-schema-traverse": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz", + "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==" }, "node_modules/nopt": { "version": "3.0.6", @@ -122,55 +155,45 @@ "integrity": "sha512-sR23YjmuwDSMsQVZDHbV9mPgi0RyniQlqR0AQxTC2/F3cpSjRFMH3CFPjoWvNqhC4OxPkDYNb2l8Mc1Me6D/KQ==", "peer": true }, - "node_modules/swagger-parser": { - "version": "10.0.3", - "resolved": "https://registry.npmjs.org/swagger-parser/-/swagger-parser-10.0.3.tgz", - "integrity": "sha512-nF7oMeL4KypldrQhac8RyHerJeGPD1p2xDh900GPvc+Nk7nWP6jX2FcC7WmkinMoAmoO774+AFXcWsW8gMWEIg==", - "dependencies": { - "@apidevtools/swagger-parser": "10.0.3" - }, + "node_modules/punycode": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.1.1.tgz", + "integrity": "sha512-XRsRjdf+j5ml+y/6GKHPZbrF/8p2Yga0JPtdqTIY2Xe5ohJPD9saDJJLPvp9+NSBprVvevdXZybnj2cv8OEd0A==", "engines": { - "node": ">=10" + "node": ">=6" } }, - "node_modules/validator": { - "version": "13.7.0", - "resolved": "https://registry.npmjs.org/validator/-/validator-13.7.0.tgz", - "integrity": "sha512-nYXQLCBkpJ8X6ltALua9dRrZDHVYxjJ1wgskNt1lH9fzGjs3tgojGSCBjmEPwkWS1y29+DrizMTW19Pr9uB2nw==", + "node_modules/require-from-string": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz", + "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==", "engines": { - "node": ">= 0.10" + "node": ">=0.10.0" } }, - "node_modules/z-schema": { - "version": "5.0.1", - "resolved": "https://registry.npmjs.org/z-schema/-/z-schema-5.0.1.tgz", - "integrity": "sha512-Gp8xU2lULhREqTWj9t4BEAeA7M835n4fWJ9KjGWksV3wmLUdOJo2hAr+QYvkVZIGOOTyeN274g1f95dKRsgYgQ==", + "node_modules/sprintf-js": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz", + "integrity": "sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==" + }, + "node_modules/uri-js": { + "version": "4.4.1", + "resolved": "https://registry.npmjs.org/uri-js/-/uri-js-4.4.1.tgz", + "integrity": "sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg==", "dependencies": { - "lodash.get": "^4.4.2", - "lodash.isequal": "^4.5.0", - "validator": "^13.6.0" - }, - "bin": { - "z-schema": "bin/z-schema" - }, - "engines": { - "node": ">=8.0.0" - }, - "optionalDependencies": { - "commander": "^2.7.1" + "punycode": "^2.1.0" } } }, "dependencies": { "@apidevtools/json-schema-ref-parser": { - "version": "9.0.9", - "resolved": "https://registry.npmjs.org/@apidevtools/json-schema-ref-parser/-/json-schema-ref-parser-9.0.9.tgz", - "integrity": "sha512-GBD2Le9w2+lVFoc4vswGI/TjkNIZSVp7+9xPf+X3uidBfWnAeUWmquteSyt0+VCrhNMWj/FTABISQrD3Z/YA+w==", + "version": "9.0.6", + "resolved": "https://registry.npmjs.org/@apidevtools/json-schema-ref-parser/-/json-schema-ref-parser-9.0.6.tgz", + "integrity": "sha512-M3YgsLjI0lZxvrpeGVk9Ap032W6TPQkH6pRAZz81Ac3WUNF79VQooAFnp8umjvVzUmD93NkogxEwbSce7qMsUg==", "requires": { "@jsdevtools/ono": "^7.1.3", - "@types/json-schema": "^7.0.6", "call-me-maybe": "^1.0.1", - "js-yaml": "^4.1.0" + "js-yaml": "^3.13.1" } }, "@apidevtools/openapi-schemas": { @@ -184,16 +207,17 @@ "integrity": "sha512-QAkD5kK2b1WfjDS/UQn/qQkbwF31uqRjPTrsCs5ZG9BQGAkjwvqGFjjPqAuzac/IYzpPtRzjCP1WrTuAIjMrXg==" }, "@apidevtools/swagger-parser": { - "version": "10.0.3", - "resolved": "https://registry.npmjs.org/@apidevtools/swagger-parser/-/swagger-parser-10.0.3.tgz", - "integrity": "sha512-sNiLY51vZOmSPFZA5TF35KZ2HbgYklQnTSDnkghamzLb3EkNtcQnrBQEj5AOCxHpTtXpqMCRM1CrmV2rG6nw4g==", + "version": "10.1.0", + "resolved": "https://registry.npmjs.org/@apidevtools/swagger-parser/-/swagger-parser-10.1.0.tgz", + "integrity": "sha512-9Kt7EuS/7WbMAUv2gSziqjvxwDbFSg3Xeyfuj5laUODX8o/k/CpsAKiQ8W7/R88eXFTMbJYg6+7uAmOWNKmwnw==", "requires": { - "@apidevtools/json-schema-ref-parser": "^9.0.6", - "@apidevtools/openapi-schemas": "^2.0.4", + "@apidevtools/json-schema-ref-parser": "9.0.6", + "@apidevtools/openapi-schemas": "^2.1.0", "@apidevtools/swagger-methods": "^3.0.2", "@jsdevtools/ono": "^7.1.3", - "call-me-maybe": "^1.0.1", - "z-schema": "^5.0.1" + "ajv": "^8.6.3", + "ajv-draft-04": "^1.0.0", + "call-me-maybe": "^1.0.1" } }, "@jsdevtools/ono": { @@ -201,49 +225,64 @@ "resolved": "https://registry.npmjs.org/@jsdevtools/ono/-/ono-7.1.3.tgz", "integrity": "sha512-4JQNk+3mVzK3xh2rqd6RB4J46qUR19azEHBneZyTZM+c456qOrbbM/5xcR8huNCCcbVt7+UmizG6GuUvPvKUYg==" }, - "@types/json-schema": { - "version": "7.0.9", - "resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.9.tgz", - "integrity": "sha512-qcUXuemtEu+E5wZSJHNxUXeCZhAfXKQ41D+duX+VYPde7xyEVZci+/oXKJL13tnRs9lR2pr4fod59GT6/X1/yQ==" - }, "abbrev": { "version": "1.1.1", "resolved": "https://registry.npmjs.org/abbrev/-/abbrev-1.1.1.tgz", "integrity": "sha512-nne9/IiQ/hzIhY6pdDnbBtz7DjPTKrY00P/zvPSm5pOFkl6xuGrGnXn/VtTNNfNtAfZ9/1RtehkszU9qcTii0Q==" }, + "ajv": { + "version": "8.11.0", + "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.11.0.tgz", + "integrity": "sha512-wGgprdCvMalC0BztXvitD2hC04YffAvtsUn93JbGXYLAtCUO4xd17mCCZQxUOItiBwZvJScWo8NIvQMQ71rdpg==", + "requires": { + "fast-deep-equal": "^3.1.1", + "json-schema-traverse": "^1.0.0", + "require-from-string": "^2.0.2", + "uri-js": "^4.2.2" + } + }, + "ajv-draft-04": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/ajv-draft-04/-/ajv-draft-04-1.0.0.tgz", + "integrity": "sha512-mv00Te6nmYbRp5DCwclxtt7yV/joXJPGS7nM+97GdxvuttCOfgI3K4U25zboyeX0O+myI8ERluxQe5wljMmVIw==", + "requires": {} + }, "argparse": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", - "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==" + "version": "1.0.10", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz", + "integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==", + "requires": { + "sprintf-js": "~1.0.2" + } }, "call-me-maybe": { "version": "1.0.1", "resolved": "https://registry.npmjs.org/call-me-maybe/-/call-me-maybe-1.0.1.tgz", - "integrity": "sha1-JtII6onje1y95gJQoV8DHBak1ms=" + "integrity": "sha512-wCyFsDQkKPwwF8BDwOiWNx/9K45L/hvggQiDbve+viMNMQnWhrlYIuBk09offfwCRtCO9P6XwUttufzU11WCVw==" + }, + "esprima": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz", + "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==" }, - "commander": { - "version": "2.20.3", - "resolved": "https://registry.npmjs.org/commander/-/commander-2.20.3.tgz", - "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==", - "optional": true + "fast-deep-equal": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz", + "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==" }, "js-yaml": { - "version": "4.1.0", - "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz", - "integrity": "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==", + "version": "3.14.1", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.14.1.tgz", + "integrity": "sha512-okMH7OXXJ7YrN9Ok3/SXrnu4iX9yOk+25nqX4imS2npuvTYDmo/QEZoqwZkYaIDk3jVvBOTOIEgEhaLOynBS9g==", "requires": { - "argparse": "^2.0.1" + "argparse": "^1.0.7", + "esprima": "^4.0.0" } }, - "lodash.get": { - "version": "4.4.2", - "resolved": "https://registry.npmjs.org/lodash.get/-/lodash.get-4.4.2.tgz", - "integrity": "sha1-LRd/ZS+jHpObRDjVNBSZ36OCXpk=" - }, - "lodash.isequal": { - "version": "4.5.0", - "resolved": "https://registry.npmjs.org/lodash.isequal/-/lodash.isequal-4.5.0.tgz", - "integrity": "sha1-QVxEePK8wwEgwizhDtMib30+GOA=" + "json-schema-traverse": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz", + "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==" }, "nopt": { "version": "3.0.6", @@ -259,28 +298,27 @@ "integrity": "sha512-sR23YjmuwDSMsQVZDHbV9mPgi0RyniQlqR0AQxTC2/F3cpSjRFMH3CFPjoWvNqhC4OxPkDYNb2l8Mc1Me6D/KQ==", "peer": true }, - "swagger-parser": { - "version": "10.0.3", - "resolved": "https://registry.npmjs.org/swagger-parser/-/swagger-parser-10.0.3.tgz", - "integrity": "sha512-nF7oMeL4KypldrQhac8RyHerJeGPD1p2xDh900GPvc+Nk7nWP6jX2FcC7WmkinMoAmoO774+AFXcWsW8gMWEIg==", - "requires": { - "@apidevtools/swagger-parser": "10.0.3" - } - }, - "validator": { - "version": "13.7.0", - "resolved": "https://registry.npmjs.org/validator/-/validator-13.7.0.tgz", - "integrity": "sha512-nYXQLCBkpJ8X6ltALua9dRrZDHVYxjJ1wgskNt1lH9fzGjs3tgojGSCBjmEPwkWS1y29+DrizMTW19Pr9uB2nw==" - }, - "z-schema": { - "version": "5.0.1", - "resolved": "https://registry.npmjs.org/z-schema/-/z-schema-5.0.1.tgz", - "integrity": "sha512-Gp8xU2lULhREqTWj9t4BEAeA7M835n4fWJ9KjGWksV3wmLUdOJo2hAr+QYvkVZIGOOTyeN274g1f95dKRsgYgQ==", + "punycode": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.1.1.tgz", + "integrity": "sha512-XRsRjdf+j5ml+y/6GKHPZbrF/8p2Yga0JPtdqTIY2Xe5ohJPD9saDJJLPvp9+NSBprVvevdXZybnj2cv8OEd0A==" + }, + "require-from-string": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz", + "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==" + }, + "sprintf-js": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz", + "integrity": "sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==" + }, + "uri-js": { + "version": "4.4.1", + "resolved": "https://registry.npmjs.org/uri-js/-/uri-js-4.4.1.tgz", + "integrity": "sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg==", "requires": { - "commander": "^2.7.1", - "lodash.get": "^4.4.2", - "lodash.isequal": "^4.5.0", - "validator": "^13.6.0" + "punycode": "^2.1.0" } } } diff --git a/scripts/package.json b/scripts/package.json index d4342c561..011a6e105 100644 --- a/scripts/package.json +++ b/scripts/package.json @@ -9,7 +9,7 @@ "author": "", "license": "ISC", "dependencies": { - "nopt": "^3.0.2", - "swagger-parser": "^10.0.3" + "@apidevtools/swagger-parser": "^10.1.0", + "nopt": "^3.0.2" } } diff --git a/scripts/validator.js b/scripts/validator.js index c20dd9930..f3b86158b 100644 --- a/scripts/validator.js +++ b/scripts/validator.js @@ -1,7 +1,7 @@ "use strict"; var fs = require("fs"); var nopt = require("nopt"); -var parser = require("swagger-parser"); +var parser = require("@apidevtools/swagger-parser"); var path = require("path"); var opts = nopt({ @@ -14,8 +14,8 @@ var opts = nopt({ if (opts.help) { console.log( - "Use swagger-parser to validate against Swagger 2.0\n"+ - "Usage:\n"+ + "Use swagger-parser to validate against OpenAPI 3.1.0\n" + + "Usage:\n" + " node validator.js -s " ); process.exit(0); @@ -26,7 +26,7 @@ if (!opts.schema) { } -var errFn = function(err, api) { +var errFn = function (err, api) { if (!err) { return; } @@ -45,7 +45,7 @@ var errFn = function(err, api) { function makeHandler(scope) { if (!scope) scope = "Schema"; - return function(err, api, metadata) { + return function (err, api, metadata) { if (err) { console.error("%s is not valid.", scope || "Schema"); errFn(err, api, metadata); // Won't return @@ -68,11 +68,11 @@ function makeHandler(scope) { var isDir = fs.lstatSync(opts.schema).isDirectory(); if (isDir) { console.log("Checking directory %s for .yaml files...", opts.schema); - fs.readdir(opts.schema, function(err, files) { + fs.readdir(opts.schema, function (err, files) { if (err) { errFn(err); // Won't return } - files.forEach(function(f) { + files.forEach(function (f) { var suffix = ".yaml"; if (f.indexOf(suffix, f.length - suffix.length) > 0) { parser.validate(path.join(opts.schema, f), makeHandler(f)); @@ -80,7 +80,7 @@ if (isDir) { }); }); } -else{ +else { parser.validate(opts.schema, makeHandler(opts.schema)); } From 02f2c47f3ce4fbcc145df55ad966a0ebd44ad476 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Tue, 9 May 2023 16:26:42 +0200 Subject: [PATCH 5/7] Update layouts for OpenAPI 3.1 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- .../json-schema/resolve-additional-types.html | 4 +- .../partials/openapi/render-object-table.html | 11 +++- .../partials/openapi/render-operation.html | 2 +- .../partials/openapi/render-parameters.html | 8 ++- layouts/partials/openapi/render-request.html | 56 +++++++++++-------- .../partials/openapi/render-responses.html | 25 ++++++--- layouts/shortcodes/http-api.html | 2 +- 7 files changed, 70 insertions(+), 38 deletions(-) diff --git a/layouts/partials/json-schema/resolve-additional-types.html b/layouts/partials/json-schema/resolve-additional-types.html index a8f25be4b..58710076e 100644 --- a/layouts/partials/json-schema/resolve-additional-types.html +++ b/layouts/partials/json-schema/resolve-additional-types.html @@ -70,8 +70,8 @@ {{/* Add any nested objects referenced in this object's `items` */}} - {{ if reflect.IsSlice $this_object.items}} - {{ range $idx, $item := $this_object.items }} + {{ if $this_object.items.anyOf }} + {{ range $idx, $item := $this_object.items.anyOf }} {{ $additional_objects = partial "get-additional-objects" (dict "this_object" $item "additional_objects" $additional_objects diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html index 67e3dc01d..5c38be87a 100644 --- a/layouts/partials/openapi/render-object-table.html +++ b/layouts/partials/openapi/render-object-table.html @@ -102,9 +102,16 @@ internal structure, handle this with a bit of recursion */}} {{ $type = delimit (slice "{string: " (partial "type-or-title" .additionalProperties) "}" ) "" }} - {{ else if reflect.IsSlice .type }} + {{ else if and .oneOf (reflect.IsSlice .oneOf) }} {{/* It's legal to specify an array of types. Join them together in that case */}} - {{ $type = delimit .type "|" }} + + {{ $types := slice }} + + {{ range .oneOf }} + {{ $types = $types | append .type }} + {{ end }} + + {{ $type = delimit $types "|" }} {{ else }} {{ $type = .type }} {{ end }} diff --git a/layouts/partials/openapi/render-operation.html b/layouts/partials/openapi/render-operation.html index 1e4806714..6486f39c7 100644 --- a/layouts/partials/openapi/render-operation.html +++ b/layouts/partials/openapi/render-operation.html @@ -64,7 +64,7 @@

-{{ partial "openapi/render-request" (dict "parameters" $operation_data.parameters "path" $path "anchor_base" $anchor ) }} +{{ partial "openapi/render-request" (dict "parameters" $operation_data.parameters "request_body" $operation_data.requestBody "path" $path "anchor_base" $anchor ) }}
{{ partial "openapi/render-responses" (dict "responses" $operation_data.responses "path" $path "anchor_base" $anchor ) }} diff --git a/layouts/partials/openapi/render-parameters.html b/layouts/partials/openapi/render-parameters.html index b7861b7f2..0e643a259 100644 --- a/layouts/partials/openapi/render-parameters.html +++ b/layouts/partials/openapi/render-parameters.html @@ -21,7 +21,13 @@ {{/* build a dict mapping from name->parameter, which render-object-table expects */}} {{ $param_dict := dict }} {{ range $parameter := . }} - {{ $param_dict = merge $param_dict (dict $parameter.name $parameter )}} + {{/* + merge the schema at the same level as the rest of the other fields because that is + what `render-object-table` expects. Put the schema first so examples in it are + overwritten. + */}} + {{ $param := merge $parameter.schema $parameter }} + {{ $param_dict = merge $param_dict (dict $parameter.name $param )}} {{ end }} {{/* and render the parameters */}} diff --git a/layouts/partials/openapi/render-request.html b/layouts/partials/openapi/render-request.html index be39fa38c..36b846da6 100644 --- a/layouts/partials/openapi/render-request.html +++ b/layouts/partials/openapi/render-request.html @@ -3,6 +3,7 @@ Render the request part of a single HTTP API operation, given: * `parameters`: OpenAPI/Swagger data specifying the parameters + * `request_body`: OpenAPI/Swagger data specifying the request body * `path`: the path where this definition was found, to enable us to resolve "$ref" * `anchor_base`: a prefix to add to the HTML anchors generated for each object @@ -14,48 +15,57 @@ */}} {{ $parameters := .parameters }} +{{ $request_body := .request_body }} {{ $path := .path }} {{ $anchor_base := .anchor_base }}

Request

-{{ if $parameters }} +{{ if or $parameters $request_body }} - {{ $simple_parameters := where $parameters "in" "!=" "body"}} - {{ if $simple_parameters }} + {{ if $parameters }}

Request parameters

- {{ partial "openapi/render-parameters" (dict "parameters" $simple_parameters "type" "header" "caption" "header parameters") }} - {{ partial "openapi/render-parameters" (dict "parameters" $simple_parameters "type" "path" "caption" "path parameters") }} - {{ partial "openapi/render-parameters" (dict "parameters" $simple_parameters "type" "query" "caption" "query parameters") }} + {{ partial "openapi/render-parameters" (dict "parameters" $parameters "type" "header" "caption" "header parameters") }} + {{ partial "openapi/render-parameters" (dict "parameters" $parameters "type" "path" "caption" "path parameters") }} + {{ partial "openapi/render-parameters" (dict "parameters" $parameters "type" "query" "caption" "query parameters") }} {{ end }} - {{ $body_parameters := where $parameters "in" "body"}} - {{ if $body_parameters }} + {{ if $request_body }}

Request body

- - {{/* at most one body param is allowed by the spec */}} - {{ $body_parameter := index $body_parameters 0 }} - {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $body_parameter.schema "path" $path) }} - {{ $schema := partial "json-schema/resolve-allof" $schema }} - - {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor_base) }} - {{ $additional_types = uniq $additional_types }} - {{ range $additional_types }} - {{ partial "openapi/render-object-table" . }} + {{/* + A request can have several content types. Only show the schema for JSON. + */}} + {{ $json_body := index $request_body.content "application/json" }} + {{ if $json_body }} + {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $json_body.schema "path" $path) }} + {{ $schema := partial "json-schema/resolve-allof" $schema }} + + {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor_base) }} + {{ $additional_types = uniq $additional_types }} + {{ range $additional_types }} + {{ partial "openapi/render-object-table" . }} + {{ end }} {{ end }}

Request body example

- - {{ $example := partial "json-schema/resolve-example" $schema }} - {{ $example_json := jsonify (dict "indent" " ") $example }} - {{ $example_json = replace $example_json "\\u003c" "<" }} - {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }} + {{/* + Show all the examples. + */}} + {{ range $mime, $body := $request_body.content }} + {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $body.schema "path" $path) }} + {{ $schema := partial "json-schema/resolve-allof" $schema }} + + {{ $example := partial "json-schema/resolve-example" $schema }} + {{ $example_json := jsonify (dict "indent" " ") $example }} + {{ $example_json = replace $example_json "\\u003c" "<" }} + {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }} ```json {{ $example_json }} ``` + {{ end }} {{ end }} {{ else }} diff --git a/layouts/partials/openapi/render-responses.html b/layouts/partials/openapi/render-responses.html index 9c59b0f2d..9ef643e58 100644 --- a/layouts/partials/openapi/render-responses.html +++ b/layouts/partials/openapi/render-responses.html @@ -38,11 +38,19 @@

Responses

{{ range $code, $response := $responses }} - {{ if $response.schema }} - + {{/* + A response can have several content types so only insert the title once. + */}} + {{ $is_title_set := false }} + {{ range $content_type, $content := $response.content }} + {{ if $content.schema }} + + {{ if not $is_title_set }} + {{ $is_title_set = true }}

{{$code}} response

+ {{ end }} - {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $response.schema "path" $path) }} + {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $content.schema "path" $path) }} {{ $schema := partial "json-schema/resolve-allof" $schema }} {{/* @@ -51,9 +59,9 @@

{{$code}} response

*/}} {{ if eq $schema.type "array" }} {{ $type_of := "" }} - {{ if reflect.IsSlice $schema.items }} + {{ if $schema.items.anyOf }} {{ $types := slice }} - {{ range $schema.items }} + {{ range $schema.items.anyOf }} {{ if .title }} {{ $types = $types | append .title}} {{ else }} @@ -84,9 +92,9 @@

{{$code}} response

*/}} {{ if or (eq $schema.type "object") (eq $schema.type "array") }} {{ $example := partial "json-schema/resolve-example" $schema }} - {{ if $response.examples }} - {{ $example = partial "json-schema/resolve-refs" (dict "schema" $response.examples "path" $path) }} - {{ $example = index $example "application/json" }} + {{ if $content.examples }} + {{ $example = partial "json-schema/resolve-refs" (dict "schema" $content.examples "path" $path) }} + {{ $example = $example.response.value }} {{ end }} {{ $example_json := jsonify (dict "indent" " ") $example }} @@ -96,6 +104,7 @@

{{$code}} response

```json {{ $example_json }} ``` + {{ end }} {{ end }} {{ end }} {{ end }} diff --git a/layouts/shortcodes/http-api.html b/layouts/shortcodes/http-api.html index 32e0ad41f..2668b1abc 100644 --- a/layouts/shortcodes/http-api.html +++ b/layouts/shortcodes/http-api.html @@ -20,7 +20,7 @@ {{ $api := .Params.api}} {{ $api_data := index .Site.Data.api .Params.spec .Params.api }} -{{ $base_url := $api_data.basePath }} +{{ $base_url := (index $api_data.servers 0).variables.basePath.default }} {{ $path := delimit (slice "api" $spec) "/" }} {{ partial "openapi/render-api" (dict "api_data" $api_data "base_url" $base_url "path" $path) }} From 902e38189fcdb2fc2ba73bbf81e9bbd5902839a0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Thu, 9 Mar 2023 20:12:09 +0100 Subject: [PATCH 6/7] Add newsfragment MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- changelogs/internal/newsfragments/1310.feature | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/internal/newsfragments/1310.feature diff --git a/changelogs/internal/newsfragments/1310.feature b/changelogs/internal/newsfragments/1310.feature new file mode 100644 index 000000000..9aaa18b63 --- /dev/null +++ b/changelogs/internal/newsfragments/1310.feature @@ -0,0 +1 @@ +Upgrade Swagger data to OpenAPI 3.1. From e2efbfbe5c0759a4403b3cfc166c46348fc5b9e1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Tue, 9 May 2023 18:51:23 +0200 Subject: [PATCH 7/7] Revert "Create Swagger 2.0 to OpenAPI 3.1 conversion scripts" This reverts commit 667c39f2595818316c158a0d136f636ae16f9143. --- .../openapi-convert/convert-definitions.mjs | 83 -- scripts/openapi-convert/index.mjs | 40 - scripts/openapi-convert/object-fixes.mjs | 49 - scripts/openapi-convert/package-lock.json | 1292 ----------------- scripts/openapi-convert/package.json | 17 - scripts/openapi-convert/string-fixes.mjs | 165 --- 6 files changed, 1646 deletions(-) delete mode 100644 scripts/openapi-convert/convert-definitions.mjs delete mode 100644 scripts/openapi-convert/index.mjs delete mode 100644 scripts/openapi-convert/object-fixes.mjs delete mode 100644 scripts/openapi-convert/package-lock.json delete mode 100644 scripts/openapi-convert/package.json delete mode 100644 scripts/openapi-convert/string-fixes.mjs diff --git a/scripts/openapi-convert/convert-definitions.mjs b/scripts/openapi-convert/convert-definitions.mjs deleted file mode 100644 index 6e3169765..000000000 --- a/scripts/openapi-convert/convert-definitions.mjs +++ /dev/null @@ -1,83 +0,0 @@ -"use strict"; -import fs from 'node:fs/promises'; -import converter from 'swagger2openapi'; -import path_utils from 'node:path'; -import yaml from 'yaml'; - -import { applyObjectFixes } from './object-fixes.mjs'; - -async function getStartComment(path) { - const file = await fs.open(path); - - let start_comment = ""; - for await (const line of file.readLines()) { - if (line.startsWith('#')) { - start_comment += line + '\n'; - } else { - break; - } - }; - - await file.close(); - - return start_comment -} - -async function convertDefinitionsFile(path) { - let relative_separator = path.lastIndexOf('/data/api'); - let short_path = path.slice(relative_separator + 1); - console.log("%s", short_path); - - // Save the comments at the start of the file to not lose them. - let start_comment = await getStartComment(path); - - // Convert. - const options = await converter.convertFile(path, { - // Patch fixable errors. - patch: true, - // Keep $ref siblings. - refSiblings: 'preserve', - // Don't deduplicate requestBodies. - resolveInternal: true, - // Write OpenAPI version 3.1.0, even if it's not completely true, it'll - // be fixed later. - targetVersion: '3.1.0', - }); - - // Apply fixes on object. - const obj = applyObjectFixes(options.openapi); - - // Serialize. - const doc = new yaml.Document(obj); - const content = yaml.stringify(doc, { - // Use "literal" blocks, like the input. - blockQuote: "literal" - }); - - // Save to file. - await fs.writeFile(path, start_comment + content); -} - -export async function convertDefinitionsDir(path) { - console.log("Converting files in %s", path); - - const files = await fs.readdir(path); - - for (const file of files) { - if (file.endsWith(".yaml")) { - await convertDefinitionsFile(path_utils.join(path, file)); - } - } -} - -// Convert Swagger 2.0 definitions to OpenAPI 3.0.0. -export async function convertDefinitions(path) { - // We don't want to try to convert schemas in subdirectories, so we need to - // call this separately for every directory inside `data/api`. - let api_dir = path_utils.join(path, "api"); - const files = await fs.readdir(api_dir); - - for (const file of files) { - await convertDefinitionsDir(path_utils.join(api_dir, file)); - } -} \ No newline at end of file diff --git a/scripts/openapi-convert/index.mjs b/scripts/openapi-convert/index.mjs deleted file mode 100644 index e7fea1b5a..000000000 --- a/scripts/openapi-convert/index.mjs +++ /dev/null @@ -1,40 +0,0 @@ -"use strict"; -import nopt from 'nopt'; - -import { convertDefinitions } from './convert-definitions.mjs'; -import { applyStringFixes } from './string-fixes.mjs'; - -const opts = nopt({ - "help": Boolean, - "data": String -}, { - "h": "--help", - "d": "--data" -}); - -console.log("params: {}", opts); -if (opts.help) { - console.log( - "Convert the definitions from Swagger 2.0 to OpenAPI 3.0\n" + - "Usage:\n" + - " node index.mjs -d " - ); - process.exit(0); -} -if (!opts.data) { - console.error("No [d]ata dir specified."); - process.exit(1); -} - -console.log("Converting Swagger 2.0 definitions to OpenAPI 3.0 in %s...", opts.data); -try { - await convertDefinitions(opts.data); - - console.log("Applying string fixes..."); - await applyStringFixes(opts.data); - - console.log(" ✅ Success"); -} catch (err) { - console.error(' ❌ {}', err); - process.exit(1); -} diff --git a/scripts/openapi-convert/object-fixes.mjs b/scripts/openapi-convert/object-fixes.mjs deleted file mode 100644 index e484f2895..000000000 --- a/scripts/openapi-convert/object-fixes.mjs +++ /dev/null @@ -1,49 +0,0 @@ -"use strict"; -import { URL } from 'node:url'; - -// Refactor `servers` field to be able to access `basePath` easily. -function refactorServers(obj) { - if (!obj.servers) { - return; - } - - let server = { - url: "", - variables: { - protocol: {}, - hostname: { - default: "" - }, - basePath: { - default: "" - } - } - } - - const url = new URL(obj.servers[0].url); - - if (obj.servers.length > 1) { - // In our case several URLs always mean both http and https for the same - // host. - obj.servers.pop() - } - - server.url = "{protocol}://{hostname}{basePath}" - server.variables.protocol = { - enum: ["http", "https"], - default: "https", - } - server.variables.hostname.default = url.host - server.variables.basePath.default = url.pathname - - obj.servers[0] = server; - - return obj; -} - -// Fixes to apply to a converted schema object. -export function applyObjectFixes(obj) { - obj = refactorServers(obj); - - return obj; -} \ No newline at end of file diff --git a/scripts/openapi-convert/package-lock.json b/scripts/openapi-convert/package-lock.json deleted file mode 100644 index 408d7fecf..000000000 --- a/scripts/openapi-convert/package-lock.json +++ /dev/null @@ -1,1292 +0,0 @@ -{ - "name": "openapi-convert", - "version": "1.0.0", - "lockfileVersion": 2, - "requires": true, - "packages": { - "": { - "name": "openapi-convert", - "version": "1.0.0", - "license": "ISC", - "dependencies": { - "nopt": "^3.0.2", - "replace": "^1.2.2", - "swagger2openapi": "^7.0.8", - "yaml": "^2.1.3" - } - }, - "node_modules/@exodus/schemasafe": { - "version": "1.0.0-rc.9", - "resolved": "https://registry.npmjs.org/@exodus/schemasafe/-/schemasafe-1.0.0-rc.9.tgz", - "integrity": "sha512-dGGHpb61hLwifAu7sotuHFDBw6GTdpG8aKC0fsK17EuTzMRvUrH7lEAr6LTJ+sx3AZYed9yZ77rltVDHyg2hRg==" - }, - "node_modules/abbrev": { - "version": "1.1.1", - "resolved": "https://registry.npmjs.org/abbrev/-/abbrev-1.1.1.tgz", - "integrity": "sha512-nne9/IiQ/hzIhY6pdDnbBtz7DjPTKrY00P/zvPSm5pOFkl6xuGrGnXn/VtTNNfNtAfZ9/1RtehkszU9qcTii0Q==" - }, - "node_modules/ansi-regex": { - "version": "5.0.1", - "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", - "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", - "engines": { - "node": ">=8" - } - }, - "node_modules/ansi-styles": { - "version": "4.3.0", - "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", - "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", - "dependencies": { - "color-convert": "^2.0.1" - }, - "engines": { - "node": ">=8" - }, - "funding": { - "url": "https://github.com/chalk/ansi-styles?sponsor=1" - } - }, - "node_modules/balanced-match": { - "version": "1.0.2", - "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz", - "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==" - }, - "node_modules/brace-expansion": { - "version": "1.1.11", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz", - "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==", - "dependencies": { - "balanced-match": "^1.0.0", - "concat-map": "0.0.1" - } - }, - "node_modules/call-me-maybe": { - "version": "1.0.2", - "resolved": "https://registry.npmjs.org/call-me-maybe/-/call-me-maybe-1.0.2.tgz", - "integrity": "sha512-HpX65o1Hnr9HH25ojC1YGs7HCQLq0GCOibSaWER0eNpgJ/Z1MZv2mTc7+xh6WOPxbRVcmgbv4hGU+uSQ/2xFZQ==" - }, - "node_modules/camelcase": { - "version": "5.3.1", - "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-5.3.1.tgz", - "integrity": "sha512-L28STB170nwWS63UjtlEOE3dldQApaJXZkOI1uMFfzf3rRuPegHaHesyee+YxQ+W6SvRDQV6UrdOdRiR153wJg==", - "engines": { - "node": ">=6" - } - }, - "node_modules/chalk": { - "version": "2.4.2", - "resolved": "https://registry.npmjs.org/chalk/-/chalk-2.4.2.tgz", - "integrity": "sha512-Mti+f9lpJNcwF4tWV8/OrTTtF1gZi+f8FqlyAdouralcFWFQWF2+NgCHShjkCb+IFBLq9buZwE1xckQU4peSuQ==", - "dependencies": { - "ansi-styles": "^3.2.1", - "escape-string-regexp": "^1.0.5", - "supports-color": "^5.3.0" - }, - "engines": { - "node": ">=4" - } - }, - "node_modules/chalk/node_modules/ansi-styles": { - "version": "3.2.1", - "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-3.2.1.tgz", - "integrity": "sha512-VT0ZI6kZRdTh8YyJw3SMbYm/u+NqfsAxEpWO0Pf9sq8/e94WxxOpPKx9FR1FlyCtOVDNOQ+8ntlqFxiRc+r5qA==", - "dependencies": { - "color-convert": "^1.9.0" - }, - "engines": { - "node": ">=4" - } - }, - "node_modules/chalk/node_modules/color-convert": { - "version": "1.9.3", - "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-1.9.3.tgz", - "integrity": "sha512-QfAUtd+vFdAtFQcC8CCyYt1fYWxSqAiK2cSD6zDB8N3cpsEBAvRxp9zOGg6G/SHHJYAT88/az/IuDGALsNVbGg==", - "dependencies": { - "color-name": "1.1.3" - } - }, - "node_modules/chalk/node_modules/color-name": { - "version": "1.1.3", - "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.3.tgz", - "integrity": "sha512-72fSenhMw2HZMTVHeCA9KCmpEIbzWiQsjN+BHcBbS9vr1mtt+vJjPdksIBNUmKAW8TFUDPJK5SUU3QhE9NEXDw==" - }, - "node_modules/cliui": { - "version": "8.0.1", - "resolved": "https://registry.npmjs.org/cliui/-/cliui-8.0.1.tgz", - "integrity": "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==", - "dependencies": { - "string-width": "^4.2.0", - "strip-ansi": "^6.0.1", - "wrap-ansi": "^7.0.0" - }, - "engines": { - "node": ">=12" - } - }, - "node_modules/color-convert": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", - "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", - "dependencies": { - "color-name": "~1.1.4" - }, - "engines": { - "node": ">=7.0.0" - } - }, - "node_modules/color-name": { - "version": "1.1.4", - "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", - "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==" - }, - "node_modules/concat-map": { - "version": "0.0.1", - "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz", - "integrity": "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==" - }, - "node_modules/decamelize": { - "version": "1.2.0", - "resolved": "https://registry.npmjs.org/decamelize/-/decamelize-1.2.0.tgz", - "integrity": "sha512-z2S+W9X73hAUUki+N+9Za2lBlun89zigOyGrsax+KUQ6wKW4ZoWpEYBkGhQjwAjjDCkWxhY0VKEhk8wzY7F5cA==", - "engines": { - "node": ">=0.10.0" - } - }, - "node_modules/emoji-regex": { - "version": "8.0.0", - "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz", - "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==" - }, - "node_modules/es6-promise": { - "version": "3.3.1", - "resolved": "https://registry.npmjs.org/es6-promise/-/es6-promise-3.3.1.tgz", - "integrity": "sha512-SOp9Phqvqn7jtEUxPWdWfWoLmyt2VaJ6MpvP9Comy1MceMXqE6bxvaTu4iaxpYYPzhny28Lc+M87/c2cPK6lDg==" - }, - "node_modules/escalade": { - "version": "3.1.1", - "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.1.1.tgz", - "integrity": "sha512-k0er2gUkLf8O0zKJiAhmkTnJlTvINGv7ygDNPbeIsX/TJjGJZHuh9B2UxbsaEkmlEo9MfhrSzmhIlhRlI2GXnw==", - "engines": { - "node": ">=6" - } - }, - "node_modules/escape-string-regexp": { - "version": "1.0.5", - "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-1.0.5.tgz", - "integrity": "sha512-vbRorB5FUQWvla16U8R/qgaFIya2qGzwDrNmCZuYKrbdSUMG6I1ZCGQRefkRVhuOkIGVne7BQ35DSfo1qvJqFg==", - "engines": { - "node": ">=0.8.0" - } - }, - "node_modules/fast-safe-stringify": { - "version": "2.1.1", - "resolved": "https://registry.npmjs.org/fast-safe-stringify/-/fast-safe-stringify-2.1.1.tgz", - "integrity": "sha512-W+KJc2dmILlPplD/H4K9l9LcAHAfPtP6BY84uVLXQ6Evcz9Lcg33Y2z1IVblT6xdY54PXYVHEv+0Wpq8Io6zkA==" - }, - "node_modules/find-up": { - "version": "4.1.0", - "resolved": "https://registry.npmjs.org/find-up/-/find-up-4.1.0.tgz", - "integrity": "sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw==", - "dependencies": { - "locate-path": "^5.0.0", - "path-exists": "^4.0.0" - }, - "engines": { - "node": ">=8" - } - }, - "node_modules/get-caller-file": { - "version": "2.0.5", - "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz", - "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==", - "engines": { - "node": "6.* || 8.* || >= 10.*" - } - }, - "node_modules/has-flag": { - "version": "3.0.0", - "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-3.0.0.tgz", - "integrity": "sha512-sKJf1+ceQBr4SMkvQnBDNDtf4TXpVhVGateu0t918bl30FnbE2m4vNLX+VWe/dpjlb+HugGYzW7uQXH98HPEYw==", - "engines": { - "node": ">=4" - } - }, - "node_modules/http2-client": { - "version": "1.3.5", - "resolved": "https://registry.npmjs.org/http2-client/-/http2-client-1.3.5.tgz", - "integrity": "sha512-EC2utToWl4RKfs5zd36Mxq7nzHHBuomZboI0yYL6Y0RmBgT7Sgkq4rQ0ezFTYoIsSs7Tm9SJe+o2FcAg6GBhGA==" - }, - "node_modules/is-fullwidth-code-point": { - "version": "3.0.0", - "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", - "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==", - "engines": { - "node": ">=8" - } - }, - "node_modules/locate-path": { - "version": "5.0.0", - "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-5.0.0.tgz", - "integrity": "sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g==", - "dependencies": { - "p-locate": "^4.1.0" - }, - "engines": { - "node": ">=8" - } - }, - "node_modules/minimatch": { - "version": "3.0.5", - "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.0.5.tgz", - "integrity": "sha512-tUpxzX0VAzJHjLu0xUfFv1gwVp9ba3IOuRAVH2EGuRW8a5emA2FlACLqiT/lDVtS1W+TGNwqz3sWaNyLgDJWuw==", - "dependencies": { - "brace-expansion": "^1.1.7" - }, - "engines": { - "node": "*" - } - }, - "node_modules/node-fetch": { - "version": "2.6.7", - "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.6.7.tgz", - "integrity": "sha512-ZjMPFEfVx5j+y2yF35Kzx5sF7kDzxuDj6ziH4FFbOp87zKDZNx8yExJIb05OGF4Nlt9IHFIMBkRl41VdvcNdbQ==", - "dependencies": { - "whatwg-url": "^5.0.0" - }, - "engines": { - "node": "4.x || >=6.0.0" - }, - "peerDependencies": { - "encoding": "^0.1.0" - }, - "peerDependenciesMeta": { - "encoding": { - "optional": true - } - } - }, - "node_modules/node-fetch-h2": { - "version": "2.3.0", - "resolved": "https://registry.npmjs.org/node-fetch-h2/-/node-fetch-h2-2.3.0.tgz", - "integrity": "sha512-ofRW94Ab0T4AOh5Fk8t0h8OBWrmjb0SSB20xh1H8YnPV9EJ+f5AMoYSUQ2zgJ4Iq2HAK0I2l5/Nequ8YzFS3Hg==", - "dependencies": { - "http2-client": "^1.2.5" - }, - "engines": { - "node": "4.x || >=6.0.0" - } - }, - "node_modules/node-readfiles": { - "version": "0.2.0", - "resolved": "https://registry.npmjs.org/node-readfiles/-/node-readfiles-0.2.0.tgz", - "integrity": "sha512-SU00ZarexNlE4Rjdm83vglt5Y9yiQ+XI1XpflWlb7q7UTN1JUItm69xMeiQCTxtTfnzt+83T8Cx+vI2ED++VDA==", - "dependencies": { - "es6-promise": "^3.2.1" - } - }, - "node_modules/nopt": { - "version": "3.0.2", - "resolved": "https://registry.npmjs.org/nopt/-/nopt-3.0.2.tgz", - "integrity": "sha512-WoB9oKq8r03hlIeU/PvXzsE2XaI97VQMSbw+8YoybgGI/Mow+qeFi7TDpVLCFEBaAhnp8uj5f7kQsuTgTCjRFA==", - "dependencies": { - "abbrev": "1" - }, - "bin": { - "nopt": "bin/nopt.js" - } - }, - "node_modules/oas-kit-common": { - "version": "1.0.8", - "resolved": "https://registry.npmjs.org/oas-kit-common/-/oas-kit-common-1.0.8.tgz", - "integrity": "sha512-pJTS2+T0oGIwgjGpw7sIRU8RQMcUoKCDWFLdBqKB2BNmGpbBMH2sdqAaOXUg8OzonZHU0L7vfJu1mJFEiYDWOQ==", - "dependencies": { - "fast-safe-stringify": "^2.0.7" - } - }, - "node_modules/oas-linter": { - "version": "3.2.2", - "resolved": "https://registry.npmjs.org/oas-linter/-/oas-linter-3.2.2.tgz", - "integrity": "sha512-KEGjPDVoU5K6swgo9hJVA/qYGlwfbFx+Kg2QB/kd7rzV5N8N5Mg6PlsoCMohVnQmo+pzJap/F610qTodKzecGQ==", - "dependencies": { - "@exodus/schemasafe": "^1.0.0-rc.2", - "should": "^13.2.1", - "yaml": "^1.10.0" - }, - "funding": { - "url": "https://github.com/Mermade/oas-kit?sponsor=1" - } - }, - "node_modules/oas-linter/node_modules/yaml": { - "version": "1.10.2", - "resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.2.tgz", - "integrity": "sha512-r3vXyErRCYJ7wg28yvBY5VSoAF8ZvlcW9/BwUzEtUsjvX/DKs24dIkuwjtuprwJJHsbyUbLApepYTR1BN4uHrg==", - "engines": { - "node": ">= 6" - } - }, - "node_modules/oas-resolver": { - "version": "2.5.6", - "resolved": "https://registry.npmjs.org/oas-resolver/-/oas-resolver-2.5.6.tgz", - "integrity": "sha512-Yx5PWQNZomfEhPPOphFbZKi9W93CocQj18NlD2Pa4GWZzdZpSJvYwoiuurRI7m3SpcChrnO08hkuQDL3FGsVFQ==", - "dependencies": { - "node-fetch-h2": "^2.3.0", - "oas-kit-common": "^1.0.8", - "reftools": "^1.1.9", - "yaml": "^1.10.0", - "yargs": "^17.0.1" - }, - "bin": { - "resolve": "resolve.js" - }, - "funding": { - "url": "https://github.com/Mermade/oas-kit?sponsor=1" - } - }, - "node_modules/oas-resolver/node_modules/yaml": { - "version": "1.10.2", - "resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.2.tgz", - "integrity": "sha512-r3vXyErRCYJ7wg28yvBY5VSoAF8ZvlcW9/BwUzEtUsjvX/DKs24dIkuwjtuprwJJHsbyUbLApepYTR1BN4uHrg==", - "engines": { - "node": ">= 6" - } - }, - "node_modules/oas-schema-walker": { - "version": "1.1.5", - "resolved": "https://registry.npmjs.org/oas-schema-walker/-/oas-schema-walker-1.1.5.tgz", - "integrity": "sha512-2yucenq1a9YPmeNExoUa9Qwrt9RFkjqaMAA1X+U7sbb0AqBeTIdMHky9SQQ6iN94bO5NW0W4TRYXerG+BdAvAQ==", - "funding": { - "url": "https://github.com/Mermade/oas-kit?sponsor=1" - } - }, - "node_modules/oas-validator": { - "version": "5.0.8", - "resolved": "https://registry.npmjs.org/oas-validator/-/oas-validator-5.0.8.tgz", - "integrity": "sha512-cu20/HE5N5HKqVygs3dt94eYJfBi0TsZvPVXDhbXQHiEityDN+RROTleefoKRKKJ9dFAF2JBkDHgvWj0sjKGmw==", - "dependencies": { - "call-me-maybe": "^1.0.1", - "oas-kit-common": "^1.0.8", - "oas-linter": "^3.2.2", - "oas-resolver": "^2.5.6", - "oas-schema-walker": "^1.1.5", - "reftools": "^1.1.9", - "should": "^13.2.1", - "yaml": "^1.10.0" - }, - "funding": { - "url": "https://github.com/Mermade/oas-kit?sponsor=1" - } - }, - "node_modules/oas-validator/node_modules/yaml": { - "version": "1.10.2", - "resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.2.tgz", - "integrity": "sha512-r3vXyErRCYJ7wg28yvBY5VSoAF8ZvlcW9/BwUzEtUsjvX/DKs24dIkuwjtuprwJJHsbyUbLApepYTR1BN4uHrg==", - "engines": { - "node": ">= 6" - } - }, - "node_modules/p-limit": { - "version": "2.3.0", - "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-2.3.0.tgz", - "integrity": "sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==", - "dependencies": { - "p-try": "^2.0.0" - }, - "engines": { - "node": ">=6" - }, - "funding": { - "url": "https://github.com/sponsors/sindresorhus" - } - }, - "node_modules/p-locate": { - "version": "4.1.0", - "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-4.1.0.tgz", - "integrity": "sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A==", - "dependencies": { - "p-limit": "^2.2.0" - }, - "engines": { - "node": ">=8" - } - }, - "node_modules/p-try": { - "version": "2.2.0", - "resolved": "https://registry.npmjs.org/p-try/-/p-try-2.2.0.tgz", - "integrity": "sha512-R4nPAVTAU0B9D35/Gk3uJf/7XYbQcyohSKdvAxIRSNghFl4e71hVoGnBNQz9cWaXxO2I10KTC+3jMdvvoKw6dQ==", - "engines": { - "node": ">=6" - } - }, - "node_modules/path-exists": { - "version": "4.0.0", - "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-4.0.0.tgz", - "integrity": "sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==", - "engines": { - "node": ">=8" - } - }, - "node_modules/reftools": { - "version": "1.1.9", - "resolved": "https://registry.npmjs.org/reftools/-/reftools-1.1.9.tgz", - "integrity": "sha512-OVede/NQE13xBQ+ob5CKd5KyeJYU2YInb1bmV4nRoOfquZPkAkxuOXicSe1PvqIuZZ4kD13sPKBbR7UFDmli6w==", - "funding": { - "url": "https://github.com/Mermade/oas-kit?sponsor=1" - } - }, - "node_modules/replace": { - "version": "1.2.2", - "resolved": "https://registry.npmjs.org/replace/-/replace-1.2.2.tgz", - "integrity": "sha512-C4EDifm22XZM2b2JOYe6Mhn+lBsLBAvLbK8drfUQLTfD1KYl/n3VaW/CDju0Ny4w3xTtegBpg8YNSpFJPUDSjA==", - "dependencies": { - "chalk": "2.4.2", - "minimatch": "3.0.5", - "yargs": "^15.3.1" - }, - "bin": { - "replace": "bin/replace.js", - "search": "bin/search.js" - }, - "engines": { - "node": ">= 6" - } - }, - "node_modules/replace/node_modules/cliui": { - "version": "6.0.0", - "resolved": "https://registry.npmjs.org/cliui/-/cliui-6.0.0.tgz", - "integrity": "sha512-t6wbgtoCXvAzst7QgXxJYqPt0usEfbgQdftEPbLL/cvv6HPE5VgvqCuAIDR0NgU52ds6rFwqrgakNLrHEjCbrQ==", - "dependencies": { - "string-width": "^4.2.0", - "strip-ansi": "^6.0.0", - "wrap-ansi": "^6.2.0" - } - }, - "node_modules/replace/node_modules/wrap-ansi": { - "version": "6.2.0", - "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-6.2.0.tgz", - "integrity": "sha512-r6lPcBGxZXlIcymEu7InxDMhdW0KDxpLgoFLcguasxCaJ/SOIZwINatK9KY/tf+ZrlywOKU0UDj3ATXUBfxJXA==", - "dependencies": { - "ansi-styles": "^4.0.0", - "string-width": "^4.1.0", - "strip-ansi": "^6.0.0" - }, - "engines": { - "node": ">=8" - } - }, - "node_modules/replace/node_modules/y18n": { - "version": "4.0.3", - "resolved": "https://registry.npmjs.org/y18n/-/y18n-4.0.3.tgz", - "integrity": "sha512-JKhqTOwSrqNA1NY5lSztJ1GrBiUodLMmIZuLiDaMRJ+itFd+ABVE8XBjOvIWL+rSqNDC74LCSFmlb/U4UZ4hJQ==" - }, - "node_modules/replace/node_modules/yargs": { - "version": "15.4.1", - "resolved": "https://registry.npmjs.org/yargs/-/yargs-15.4.1.tgz", - "integrity": "sha512-aePbxDmcYW++PaqBsJ+HYUFwCdv4LVvdnhBy78E57PIor8/OVvhMrADFFEDh8DHDFRv/O9i3lPhsENjO7QX0+A==", - "dependencies": { - "cliui": "^6.0.0", - "decamelize": "^1.2.0", - "find-up": "^4.1.0", - "get-caller-file": "^2.0.1", - "require-directory": "^2.1.1", - "require-main-filename": "^2.0.0", - "set-blocking": "^2.0.0", - "string-width": "^4.2.0", - "which-module": "^2.0.0", - "y18n": "^4.0.0", - "yargs-parser": "^18.1.2" - }, - "engines": { - "node": ">=8" - } - }, - "node_modules/replace/node_modules/yargs-parser": { - "version": "18.1.3", - "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-18.1.3.tgz", - "integrity": "sha512-o50j0JeToy/4K6OZcaQmW6lyXXKhq7csREXcDwk2omFPJEwUNOVtJKvmDr9EI1fAJZUyZcRF7kxGBWmRXudrCQ==", - "dependencies": { - "camelcase": "^5.0.0", - "decamelize": "^1.2.0" - }, - "engines": { - "node": ">=6" - } - }, - "node_modules/require-directory": { - "version": "2.1.1", - "resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz", - "integrity": "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==", - "engines": { - "node": ">=0.10.0" - } - }, - "node_modules/require-main-filename": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/require-main-filename/-/require-main-filename-2.0.0.tgz", - "integrity": "sha512-NKN5kMDylKuldxYLSUfrbo5Tuzh4hd+2E8NPPX02mZtn1VuREQToYe/ZdlJy+J3uCpfaiGF05e7B8W0iXbQHmg==" - }, - "node_modules/set-blocking": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/set-blocking/-/set-blocking-2.0.0.tgz", - "integrity": "sha512-KiKBS8AnWGEyLzofFfmvKwpdPzqiy16LvQfK3yv/fVH7Bj13/wl3JSR1J+rfgRE9q7xUJK4qvgS8raSOeLUehw==" - }, - "node_modules/should": { - "version": "13.2.3", - "resolved": "https://registry.npmjs.org/should/-/should-13.2.3.tgz", - "integrity": "sha512-ggLesLtu2xp+ZxI+ysJTmNjh2U0TsC+rQ/pfED9bUZZ4DKefP27D+7YJVVTvKsmjLpIi9jAa7itwDGkDDmt1GQ==", - "dependencies": { - "should-equal": "^2.0.0", - "should-format": "^3.0.3", - "should-type": "^1.4.0", - "should-type-adaptors": "^1.0.1", - "should-util": "^1.0.0" - } - }, - "node_modules/should-equal": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/should-equal/-/should-equal-2.0.0.tgz", - "integrity": "sha512-ZP36TMrK9euEuWQYBig9W55WPC7uo37qzAEmbjHz4gfyuXrEUgF8cUvQVO+w+d3OMfPvSRQJ22lSm8MQJ43LTA==", - "dependencies": { - "should-type": "^1.4.0" - } - }, - "node_modules/should-format": { - "version": "3.0.3", - "resolved": "https://registry.npmjs.org/should-format/-/should-format-3.0.3.tgz", - "integrity": "sha512-hZ58adtulAk0gKtua7QxevgUaXTTXxIi8t41L3zo9AHvjXO1/7sdLECuHeIN2SRtYXpNkmhoUP2pdeWgricQ+Q==", - "dependencies": { - "should-type": "^1.3.0", - "should-type-adaptors": "^1.0.1" - } - }, - "node_modules/should-type": { - "version": "1.4.0", - "resolved": "https://registry.npmjs.org/should-type/-/should-type-1.4.0.tgz", - "integrity": "sha512-MdAsTu3n25yDbIe1NeN69G4n6mUnJGtSJHygX3+oN0ZbO3DTiATnf7XnYJdGT42JCXurTb1JI0qOBR65shvhPQ==" - }, - "node_modules/should-type-adaptors": { - "version": "1.1.0", - "resolved": "https://registry.npmjs.org/should-type-adaptors/-/should-type-adaptors-1.1.0.tgz", - "integrity": "sha512-JA4hdoLnN+kebEp2Vs8eBe9g7uy0zbRo+RMcU0EsNy+R+k049Ki+N5tT5Jagst2g7EAja+euFuoXFCa8vIklfA==", - "dependencies": { - "should-type": "^1.3.0", - "should-util": "^1.0.0" - } - }, - "node_modules/should-util": { - "version": "1.0.1", - "resolved": "https://registry.npmjs.org/should-util/-/should-util-1.0.1.tgz", - "integrity": "sha512-oXF8tfxx5cDk8r2kYqlkUJzZpDBqVY/II2WhvU0n9Y3XYvAYRmeaf1PvvIvTgPnv4KJ+ES5M0PyDq5Jp+Ygy2g==" - }, - "node_modules/string-width": { - "version": "4.2.3", - "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", - "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", - "dependencies": { - "emoji-regex": "^8.0.0", - "is-fullwidth-code-point": "^3.0.0", - "strip-ansi": "^6.0.1" - }, - "engines": { - "node": ">=8" - } - }, - "node_modules/strip-ansi": { - "version": "6.0.1", - "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", - "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", - "dependencies": { - "ansi-regex": "^5.0.1" - }, - "engines": { - "node": ">=8" - } - }, - "node_modules/supports-color": { - "version": "5.5.0", - "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-5.5.0.tgz", - "integrity": "sha512-QjVjwdXIt408MIiAqCX4oUKsgU2EqAGzs2Ppkm4aQYbjm+ZEWEcW4SfFNTr4uMNZma0ey4f5lgLrkB0aX0QMow==", - "dependencies": { - "has-flag": "^3.0.0" - }, - "engines": { - "node": ">=4" - } - }, - "node_modules/swagger2openapi": { - "version": "7.0.8", - "resolved": "https://registry.npmjs.org/swagger2openapi/-/swagger2openapi-7.0.8.tgz", - "integrity": "sha512-upi/0ZGkYgEcLeGieoz8gT74oWHA0E7JivX7aN9mAf+Tc7BQoRBvnIGHoPDw+f9TXTW4s6kGYCZJtauP6OYp7g==", - "dependencies": { - "call-me-maybe": "^1.0.1", - "node-fetch": "^2.6.1", - "node-fetch-h2": "^2.3.0", - "node-readfiles": "^0.2.0", - "oas-kit-common": "^1.0.8", - "oas-resolver": "^2.5.6", - "oas-schema-walker": "^1.1.5", - "oas-validator": "^5.0.8", - "reftools": "^1.1.9", - "yaml": "^1.10.0", - "yargs": "^17.0.1" - }, - "bin": { - "boast": "boast.js", - "oas-validate": "oas-validate.js", - "swagger2openapi": "swagger2openapi.js" - }, - "funding": { - "url": "https://github.com/Mermade/oas-kit?sponsor=1" - } - }, - "node_modules/swagger2openapi/node_modules/yaml": { - "version": "1.10.2", - "resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.2.tgz", - "integrity": "sha512-r3vXyErRCYJ7wg28yvBY5VSoAF8ZvlcW9/BwUzEtUsjvX/DKs24dIkuwjtuprwJJHsbyUbLApepYTR1BN4uHrg==", - "engines": { - "node": ">= 6" - } - }, - "node_modules/tr46": { - "version": "0.0.3", - "resolved": "https://registry.npmjs.org/tr46/-/tr46-0.0.3.tgz", - "integrity": "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==" - }, - "node_modules/webidl-conversions": { - "version": "3.0.1", - "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-3.0.1.tgz", - "integrity": "sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ==" - }, - "node_modules/whatwg-url": { - "version": "5.0.0", - "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-5.0.0.tgz", - "integrity": "sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==", - "dependencies": { - "tr46": "~0.0.3", - "webidl-conversions": "^3.0.0" - } - }, - "node_modules/which-module": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/which-module/-/which-module-2.0.0.tgz", - "integrity": "sha512-B+enWhmw6cjfVC7kS8Pj9pCrKSc5txArRyaYGe088shv/FGWH+0Rjx/xPgtsWfsUtS27FkP697E4DDhgrgoc0Q==" - }, - "node_modules/wrap-ansi": { - "version": "7.0.0", - "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz", - "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==", - "dependencies": { - "ansi-styles": "^4.0.0", - "string-width": "^4.1.0", - "strip-ansi": "^6.0.0" - }, - "engines": { - "node": ">=10" - }, - "funding": { - "url": "https://github.com/chalk/wrap-ansi?sponsor=1" - } - }, - "node_modules/y18n": { - "version": "5.0.8", - "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz", - "integrity": "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==", - "engines": { - "node": ">=10" - } - }, - "node_modules/yaml": { - "version": "2.1.3", - "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.1.3.tgz", - "integrity": "sha512-AacA8nRULjKMX2DvWvOAdBZMOfQlypSFkjcOcu9FalllIDJ1kvlREzcdIZmidQUqqeMv7jorHjq2HlLv/+c2lg==", - "engines": { - "node": ">= 14" - } - }, - "node_modules/yargs": { - "version": "17.6.2", - "resolved": "https://registry.npmjs.org/yargs/-/yargs-17.6.2.tgz", - "integrity": "sha512-1/9UrdHjDZc0eOU0HxOHoS78C69UD3JRMvzlJ7S79S2nTaWRA/whGCTV8o9e/N/1Va9YIV7Q4sOxD8VV4pCWOw==", - "dependencies": { - "cliui": "^8.0.1", - "escalade": "^3.1.1", - "get-caller-file": "^2.0.5", - "require-directory": "^2.1.1", - "string-width": "^4.2.3", - "y18n": "^5.0.5", - "yargs-parser": "^21.1.1" - }, - "engines": { - "node": ">=12" - } - }, - "node_modules/yargs-parser": { - "version": "21.1.1", - "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-21.1.1.tgz", - "integrity": "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==", - "engines": { - "node": ">=12" - } - } - }, - "dependencies": { - "@exodus/schemasafe": { - "version": "1.0.0-rc.9", - "resolved": "https://registry.npmjs.org/@exodus/schemasafe/-/schemasafe-1.0.0-rc.9.tgz", - "integrity": "sha512-dGGHpb61hLwifAu7sotuHFDBw6GTdpG8aKC0fsK17EuTzMRvUrH7lEAr6LTJ+sx3AZYed9yZ77rltVDHyg2hRg==" - }, - "abbrev": { - "version": "1.1.1", - "resolved": "https://registry.npmjs.org/abbrev/-/abbrev-1.1.1.tgz", - "integrity": "sha512-nne9/IiQ/hzIhY6pdDnbBtz7DjPTKrY00P/zvPSm5pOFkl6xuGrGnXn/VtTNNfNtAfZ9/1RtehkszU9qcTii0Q==" - }, - "ansi-regex": { - "version": "5.0.1", - "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", - "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==" - }, - "ansi-styles": { - "version": "4.3.0", - "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", - "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", - "requires": { - "color-convert": "^2.0.1" - } - }, - "balanced-match": { - "version": "1.0.2", - "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz", - "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==" - }, - "brace-expansion": { - "version": "1.1.11", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz", - "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==", - "requires": { - "balanced-match": "^1.0.0", - "concat-map": "0.0.1" - } - }, - "call-me-maybe": { - "version": "1.0.2", - "resolved": "https://registry.npmjs.org/call-me-maybe/-/call-me-maybe-1.0.2.tgz", - "integrity": "sha512-HpX65o1Hnr9HH25ojC1YGs7HCQLq0GCOibSaWER0eNpgJ/Z1MZv2mTc7+xh6WOPxbRVcmgbv4hGU+uSQ/2xFZQ==" - }, - "camelcase": { - "version": "5.3.1", - "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-5.3.1.tgz", - "integrity": "sha512-L28STB170nwWS63UjtlEOE3dldQApaJXZkOI1uMFfzf3rRuPegHaHesyee+YxQ+W6SvRDQV6UrdOdRiR153wJg==" - }, - "chalk": { - "version": "2.4.2", - "resolved": "https://registry.npmjs.org/chalk/-/chalk-2.4.2.tgz", - "integrity": "sha512-Mti+f9lpJNcwF4tWV8/OrTTtF1gZi+f8FqlyAdouralcFWFQWF2+NgCHShjkCb+IFBLq9buZwE1xckQU4peSuQ==", - "requires": { - "ansi-styles": "^3.2.1", - "escape-string-regexp": "^1.0.5", - "supports-color": "^5.3.0" - }, - "dependencies": { - "ansi-styles": { - "version": "3.2.1", - "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-3.2.1.tgz", - "integrity": "sha512-VT0ZI6kZRdTh8YyJw3SMbYm/u+NqfsAxEpWO0Pf9sq8/e94WxxOpPKx9FR1FlyCtOVDNOQ+8ntlqFxiRc+r5qA==", - "requires": { - "color-convert": "^1.9.0" - } - }, - "color-convert": { - "version": "1.9.3", - "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-1.9.3.tgz", - "integrity": "sha512-QfAUtd+vFdAtFQcC8CCyYt1fYWxSqAiK2cSD6zDB8N3cpsEBAvRxp9zOGg6G/SHHJYAT88/az/IuDGALsNVbGg==", - "requires": { - "color-name": "1.1.3" - } - }, - "color-name": { - "version": "1.1.3", - "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.3.tgz", - "integrity": "sha512-72fSenhMw2HZMTVHeCA9KCmpEIbzWiQsjN+BHcBbS9vr1mtt+vJjPdksIBNUmKAW8TFUDPJK5SUU3QhE9NEXDw==" - } - } - }, - "cliui": { - "version": "8.0.1", - "resolved": "https://registry.npmjs.org/cliui/-/cliui-8.0.1.tgz", - "integrity": "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==", - "requires": { - "string-width": "^4.2.0", - "strip-ansi": "^6.0.1", - "wrap-ansi": "^7.0.0" - } - }, - "color-convert": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", - "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", - "requires": { - "color-name": "~1.1.4" - } - }, - "color-name": { - "version": "1.1.4", - "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", - "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==" - }, - "concat-map": { - "version": "0.0.1", - "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz", - "integrity": "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==" - }, - "decamelize": { - "version": "1.2.0", - "resolved": "https://registry.npmjs.org/decamelize/-/decamelize-1.2.0.tgz", - "integrity": "sha512-z2S+W9X73hAUUki+N+9Za2lBlun89zigOyGrsax+KUQ6wKW4ZoWpEYBkGhQjwAjjDCkWxhY0VKEhk8wzY7F5cA==" - }, - "emoji-regex": { - "version": "8.0.0", - "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz", - "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==" - }, - "es6-promise": { - "version": "3.3.1", - "resolved": "https://registry.npmjs.org/es6-promise/-/es6-promise-3.3.1.tgz", - "integrity": "sha512-SOp9Phqvqn7jtEUxPWdWfWoLmyt2VaJ6MpvP9Comy1MceMXqE6bxvaTu4iaxpYYPzhny28Lc+M87/c2cPK6lDg==" - }, - "escalade": { - "version": "3.1.1", - "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.1.1.tgz", - "integrity": "sha512-k0er2gUkLf8O0zKJiAhmkTnJlTvINGv7ygDNPbeIsX/TJjGJZHuh9B2UxbsaEkmlEo9MfhrSzmhIlhRlI2GXnw==" - }, - "escape-string-regexp": { - "version": "1.0.5", - "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-1.0.5.tgz", - "integrity": "sha512-vbRorB5FUQWvla16U8R/qgaFIya2qGzwDrNmCZuYKrbdSUMG6I1ZCGQRefkRVhuOkIGVne7BQ35DSfo1qvJqFg==" - }, - "fast-safe-stringify": { - "version": "2.1.1", - "resolved": "https://registry.npmjs.org/fast-safe-stringify/-/fast-safe-stringify-2.1.1.tgz", - "integrity": "sha512-W+KJc2dmILlPplD/H4K9l9LcAHAfPtP6BY84uVLXQ6Evcz9Lcg33Y2z1IVblT6xdY54PXYVHEv+0Wpq8Io6zkA==" - }, - "find-up": { - "version": "4.1.0", - "resolved": "https://registry.npmjs.org/find-up/-/find-up-4.1.0.tgz", - "integrity": "sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw==", - "requires": { - "locate-path": "^5.0.0", - "path-exists": "^4.0.0" - } - }, - "get-caller-file": { - "version": "2.0.5", - "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz", - "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==" - }, - "has-flag": { - "version": "3.0.0", - "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-3.0.0.tgz", - "integrity": "sha512-sKJf1+ceQBr4SMkvQnBDNDtf4TXpVhVGateu0t918bl30FnbE2m4vNLX+VWe/dpjlb+HugGYzW7uQXH98HPEYw==" - }, - "http2-client": { - "version": "1.3.5", - "resolved": "https://registry.npmjs.org/http2-client/-/http2-client-1.3.5.tgz", - "integrity": "sha512-EC2utToWl4RKfs5zd36Mxq7nzHHBuomZboI0yYL6Y0RmBgT7Sgkq4rQ0ezFTYoIsSs7Tm9SJe+o2FcAg6GBhGA==" - }, - "is-fullwidth-code-point": { - "version": "3.0.0", - "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", - "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==" - }, - "locate-path": { - "version": "5.0.0", - "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-5.0.0.tgz", - "integrity": "sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g==", - "requires": { - "p-locate": "^4.1.0" - } - }, - "minimatch": { - "version": "3.0.5", - "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.0.5.tgz", - "integrity": "sha512-tUpxzX0VAzJHjLu0xUfFv1gwVp9ba3IOuRAVH2EGuRW8a5emA2FlACLqiT/lDVtS1W+TGNwqz3sWaNyLgDJWuw==", - "requires": { - "brace-expansion": "^1.1.7" - } - }, - "node-fetch": { - "version": "2.6.7", - "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.6.7.tgz", - "integrity": "sha512-ZjMPFEfVx5j+y2yF35Kzx5sF7kDzxuDj6ziH4FFbOp87zKDZNx8yExJIb05OGF4Nlt9IHFIMBkRl41VdvcNdbQ==", - "requires": { - "whatwg-url": "^5.0.0" - } - }, - "node-fetch-h2": { - "version": "2.3.0", - "resolved": "https://registry.npmjs.org/node-fetch-h2/-/node-fetch-h2-2.3.0.tgz", - "integrity": "sha512-ofRW94Ab0T4AOh5Fk8t0h8OBWrmjb0SSB20xh1H8YnPV9EJ+f5AMoYSUQ2zgJ4Iq2HAK0I2l5/Nequ8YzFS3Hg==", - "requires": { - "http2-client": "^1.2.5" - } - }, - "node-readfiles": { - "version": "0.2.0", - "resolved": "https://registry.npmjs.org/node-readfiles/-/node-readfiles-0.2.0.tgz", - "integrity": "sha512-SU00ZarexNlE4Rjdm83vglt5Y9yiQ+XI1XpflWlb7q7UTN1JUItm69xMeiQCTxtTfnzt+83T8Cx+vI2ED++VDA==", - "requires": { - "es6-promise": "^3.2.1" - } - }, - "nopt": { - "version": "3.0.2", - "resolved": "https://registry.npmjs.org/nopt/-/nopt-3.0.2.tgz", - "integrity": "sha512-WoB9oKq8r03hlIeU/PvXzsE2XaI97VQMSbw+8YoybgGI/Mow+qeFi7TDpVLCFEBaAhnp8uj5f7kQsuTgTCjRFA==", - "requires": { - "abbrev": "1" - } - }, - "oas-kit-common": { - "version": "1.0.8", - "resolved": "https://registry.npmjs.org/oas-kit-common/-/oas-kit-common-1.0.8.tgz", - "integrity": "sha512-pJTS2+T0oGIwgjGpw7sIRU8RQMcUoKCDWFLdBqKB2BNmGpbBMH2sdqAaOXUg8OzonZHU0L7vfJu1mJFEiYDWOQ==", - "requires": { - "fast-safe-stringify": "^2.0.7" - } - }, - "oas-linter": { - "version": "3.2.2", - "resolved": "https://registry.npmjs.org/oas-linter/-/oas-linter-3.2.2.tgz", - "integrity": "sha512-KEGjPDVoU5K6swgo9hJVA/qYGlwfbFx+Kg2QB/kd7rzV5N8N5Mg6PlsoCMohVnQmo+pzJap/F610qTodKzecGQ==", - "requires": { - "@exodus/schemasafe": "^1.0.0-rc.2", - "should": "^13.2.1", - "yaml": "^1.10.0" - }, - "dependencies": { - "yaml": { - "version": "1.10.2", - "resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.2.tgz", - "integrity": "sha512-r3vXyErRCYJ7wg28yvBY5VSoAF8ZvlcW9/BwUzEtUsjvX/DKs24dIkuwjtuprwJJHsbyUbLApepYTR1BN4uHrg==" - } - } - }, - "oas-resolver": { - "version": "2.5.6", - "resolved": "https://registry.npmjs.org/oas-resolver/-/oas-resolver-2.5.6.tgz", - "integrity": "sha512-Yx5PWQNZomfEhPPOphFbZKi9W93CocQj18NlD2Pa4GWZzdZpSJvYwoiuurRI7m3SpcChrnO08hkuQDL3FGsVFQ==", - "requires": { - "node-fetch-h2": "^2.3.0", - "oas-kit-common": "^1.0.8", - "reftools": "^1.1.9", - "yaml": "^1.10.0", - "yargs": "^17.0.1" - }, - "dependencies": { - "yaml": { - "version": "1.10.2", - "resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.2.tgz", - "integrity": "sha512-r3vXyErRCYJ7wg28yvBY5VSoAF8ZvlcW9/BwUzEtUsjvX/DKs24dIkuwjtuprwJJHsbyUbLApepYTR1BN4uHrg==" - } - } - }, - "oas-schema-walker": { - "version": "1.1.5", - "resolved": "https://registry.npmjs.org/oas-schema-walker/-/oas-schema-walker-1.1.5.tgz", - "integrity": "sha512-2yucenq1a9YPmeNExoUa9Qwrt9RFkjqaMAA1X+U7sbb0AqBeTIdMHky9SQQ6iN94bO5NW0W4TRYXerG+BdAvAQ==" - }, - "oas-validator": { - "version": "5.0.8", - "resolved": "https://registry.npmjs.org/oas-validator/-/oas-validator-5.0.8.tgz", - "integrity": "sha512-cu20/HE5N5HKqVygs3dt94eYJfBi0TsZvPVXDhbXQHiEityDN+RROTleefoKRKKJ9dFAF2JBkDHgvWj0sjKGmw==", - "requires": { - "call-me-maybe": "^1.0.1", - "oas-kit-common": "^1.0.8", - "oas-linter": "^3.2.2", - "oas-resolver": "^2.5.6", - "oas-schema-walker": "^1.1.5", - "reftools": "^1.1.9", - "should": "^13.2.1", - "yaml": "^1.10.0" - }, - "dependencies": { - "yaml": { - "version": "1.10.2", - "resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.2.tgz", - "integrity": "sha512-r3vXyErRCYJ7wg28yvBY5VSoAF8ZvlcW9/BwUzEtUsjvX/DKs24dIkuwjtuprwJJHsbyUbLApepYTR1BN4uHrg==" - } - } - }, - "p-limit": { - "version": "2.3.0", - "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-2.3.0.tgz", - "integrity": "sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==", - "requires": { - "p-try": "^2.0.0" - } - }, - "p-locate": { - "version": "4.1.0", - "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-4.1.0.tgz", - "integrity": "sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A==", - "requires": { - "p-limit": "^2.2.0" - } - }, - "p-try": { - "version": "2.2.0", - "resolved": "https://registry.npmjs.org/p-try/-/p-try-2.2.0.tgz", - "integrity": "sha512-R4nPAVTAU0B9D35/Gk3uJf/7XYbQcyohSKdvAxIRSNghFl4e71hVoGnBNQz9cWaXxO2I10KTC+3jMdvvoKw6dQ==" - }, - "path-exists": { - "version": "4.0.0", - "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-4.0.0.tgz", - "integrity": "sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==" - }, - "reftools": { - "version": "1.1.9", - "resolved": "https://registry.npmjs.org/reftools/-/reftools-1.1.9.tgz", - "integrity": "sha512-OVede/NQE13xBQ+ob5CKd5KyeJYU2YInb1bmV4nRoOfquZPkAkxuOXicSe1PvqIuZZ4kD13sPKBbR7UFDmli6w==" - }, - "replace": { - "version": "1.2.2", - "resolved": "https://registry.npmjs.org/replace/-/replace-1.2.2.tgz", - "integrity": "sha512-C4EDifm22XZM2b2JOYe6Mhn+lBsLBAvLbK8drfUQLTfD1KYl/n3VaW/CDju0Ny4w3xTtegBpg8YNSpFJPUDSjA==", - "requires": { - "chalk": "2.4.2", - "minimatch": "3.0.5", - "yargs": "^15.3.1" - }, - "dependencies": { - "cliui": { - "version": "6.0.0", - "resolved": "https://registry.npmjs.org/cliui/-/cliui-6.0.0.tgz", - "integrity": "sha512-t6wbgtoCXvAzst7QgXxJYqPt0usEfbgQdftEPbLL/cvv6HPE5VgvqCuAIDR0NgU52ds6rFwqrgakNLrHEjCbrQ==", - "requires": { - "string-width": "^4.2.0", - "strip-ansi": "^6.0.0", - "wrap-ansi": "^6.2.0" - } - }, - "wrap-ansi": { - "version": "6.2.0", - "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-6.2.0.tgz", - "integrity": "sha512-r6lPcBGxZXlIcymEu7InxDMhdW0KDxpLgoFLcguasxCaJ/SOIZwINatK9KY/tf+ZrlywOKU0UDj3ATXUBfxJXA==", - "requires": { - "ansi-styles": "^4.0.0", - "string-width": "^4.1.0", - "strip-ansi": "^6.0.0" - } - }, - "y18n": { - "version": "4.0.3", - "resolved": "https://registry.npmjs.org/y18n/-/y18n-4.0.3.tgz", - "integrity": "sha512-JKhqTOwSrqNA1NY5lSztJ1GrBiUodLMmIZuLiDaMRJ+itFd+ABVE8XBjOvIWL+rSqNDC74LCSFmlb/U4UZ4hJQ==" - }, - "yargs": { - "version": "15.4.1", - "resolved": "https://registry.npmjs.org/yargs/-/yargs-15.4.1.tgz", - "integrity": "sha512-aePbxDmcYW++PaqBsJ+HYUFwCdv4LVvdnhBy78E57PIor8/OVvhMrADFFEDh8DHDFRv/O9i3lPhsENjO7QX0+A==", - "requires": { - "cliui": "^6.0.0", - "decamelize": "^1.2.0", - "find-up": "^4.1.0", - "get-caller-file": "^2.0.1", - "require-directory": "^2.1.1", - "require-main-filename": "^2.0.0", - "set-blocking": "^2.0.0", - "string-width": "^4.2.0", - "which-module": "^2.0.0", - "y18n": "^4.0.0", - "yargs-parser": "^18.1.2" - } - }, - "yargs-parser": { - "version": "18.1.3", - "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-18.1.3.tgz", - "integrity": "sha512-o50j0JeToy/4K6OZcaQmW6lyXXKhq7csREXcDwk2omFPJEwUNOVtJKvmDr9EI1fAJZUyZcRF7kxGBWmRXudrCQ==", - "requires": { - "camelcase": "^5.0.0", - "decamelize": "^1.2.0" - } - } - } - }, - "require-directory": { - "version": "2.1.1", - "resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz", - "integrity": "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==" - }, - "require-main-filename": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/require-main-filename/-/require-main-filename-2.0.0.tgz", - "integrity": "sha512-NKN5kMDylKuldxYLSUfrbo5Tuzh4hd+2E8NPPX02mZtn1VuREQToYe/ZdlJy+J3uCpfaiGF05e7B8W0iXbQHmg==" - }, - "set-blocking": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/set-blocking/-/set-blocking-2.0.0.tgz", - "integrity": "sha512-KiKBS8AnWGEyLzofFfmvKwpdPzqiy16LvQfK3yv/fVH7Bj13/wl3JSR1J+rfgRE9q7xUJK4qvgS8raSOeLUehw==" - }, - "should": { - "version": "13.2.3", - "resolved": "https://registry.npmjs.org/should/-/should-13.2.3.tgz", - "integrity": "sha512-ggLesLtu2xp+ZxI+ysJTmNjh2U0TsC+rQ/pfED9bUZZ4DKefP27D+7YJVVTvKsmjLpIi9jAa7itwDGkDDmt1GQ==", - "requires": { - "should-equal": "^2.0.0", - "should-format": "^3.0.3", - "should-type": "^1.4.0", - "should-type-adaptors": "^1.0.1", - "should-util": "^1.0.0" - } - }, - "should-equal": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/should-equal/-/should-equal-2.0.0.tgz", - "integrity": "sha512-ZP36TMrK9euEuWQYBig9W55WPC7uo37qzAEmbjHz4gfyuXrEUgF8cUvQVO+w+d3OMfPvSRQJ22lSm8MQJ43LTA==", - "requires": { - "should-type": "^1.4.0" - } - }, - "should-format": { - "version": "3.0.3", - "resolved": "https://registry.npmjs.org/should-format/-/should-format-3.0.3.tgz", - "integrity": "sha512-hZ58adtulAk0gKtua7QxevgUaXTTXxIi8t41L3zo9AHvjXO1/7sdLECuHeIN2SRtYXpNkmhoUP2pdeWgricQ+Q==", - "requires": { - "should-type": "^1.3.0", - "should-type-adaptors": "^1.0.1" - } - }, - "should-type": { - "version": "1.4.0", - "resolved": "https://registry.npmjs.org/should-type/-/should-type-1.4.0.tgz", - "integrity": "sha512-MdAsTu3n25yDbIe1NeN69G4n6mUnJGtSJHygX3+oN0ZbO3DTiATnf7XnYJdGT42JCXurTb1JI0qOBR65shvhPQ==" - }, - "should-type-adaptors": { - "version": "1.1.0", - "resolved": "https://registry.npmjs.org/should-type-adaptors/-/should-type-adaptors-1.1.0.tgz", - "integrity": "sha512-JA4hdoLnN+kebEp2Vs8eBe9g7uy0zbRo+RMcU0EsNy+R+k049Ki+N5tT5Jagst2g7EAja+euFuoXFCa8vIklfA==", - "requires": { - "should-type": "^1.3.0", - "should-util": "^1.0.0" - } - }, - "should-util": { - "version": "1.0.1", - "resolved": "https://registry.npmjs.org/should-util/-/should-util-1.0.1.tgz", - "integrity": "sha512-oXF8tfxx5cDk8r2kYqlkUJzZpDBqVY/II2WhvU0n9Y3XYvAYRmeaf1PvvIvTgPnv4KJ+ES5M0PyDq5Jp+Ygy2g==" - }, - "string-width": { - "version": "4.2.3", - "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", - "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", - "requires": { - "emoji-regex": "^8.0.0", - "is-fullwidth-code-point": "^3.0.0", - "strip-ansi": "^6.0.1" - } - }, - "strip-ansi": { - "version": "6.0.1", - "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", - "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", - "requires": { - "ansi-regex": "^5.0.1" - } - }, - "supports-color": { - "version": "5.5.0", - "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-5.5.0.tgz", - "integrity": "sha512-QjVjwdXIt408MIiAqCX4oUKsgU2EqAGzs2Ppkm4aQYbjm+ZEWEcW4SfFNTr4uMNZma0ey4f5lgLrkB0aX0QMow==", - "requires": { - "has-flag": "^3.0.0" - } - }, - "swagger2openapi": { - "version": "7.0.8", - "resolved": "https://registry.npmjs.org/swagger2openapi/-/swagger2openapi-7.0.8.tgz", - "integrity": "sha512-upi/0ZGkYgEcLeGieoz8gT74oWHA0E7JivX7aN9mAf+Tc7BQoRBvnIGHoPDw+f9TXTW4s6kGYCZJtauP6OYp7g==", - "requires": { - "call-me-maybe": "^1.0.1", - "node-fetch": "^2.6.1", - "node-fetch-h2": "^2.3.0", - "node-readfiles": "^0.2.0", - "oas-kit-common": "^1.0.8", - "oas-resolver": "^2.5.6", - "oas-schema-walker": "^1.1.5", - "oas-validator": "^5.0.8", - "reftools": "^1.1.9", - "yaml": "^1.10.0", - "yargs": "^17.0.1" - }, - "dependencies": { - "yaml": { - "version": "1.10.2", - "resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.2.tgz", - "integrity": "sha512-r3vXyErRCYJ7wg28yvBY5VSoAF8ZvlcW9/BwUzEtUsjvX/DKs24dIkuwjtuprwJJHsbyUbLApepYTR1BN4uHrg==" - } - } - }, - "tr46": { - "version": "0.0.3", - "resolved": "https://registry.npmjs.org/tr46/-/tr46-0.0.3.tgz", - "integrity": "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==" - }, - "webidl-conversions": { - "version": "3.0.1", - "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-3.0.1.tgz", - "integrity": "sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ==" - }, - "whatwg-url": { - "version": "5.0.0", - "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-5.0.0.tgz", - "integrity": "sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==", - "requires": { - "tr46": "~0.0.3", - "webidl-conversions": "^3.0.0" - } - }, - "which-module": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/which-module/-/which-module-2.0.0.tgz", - "integrity": "sha512-B+enWhmw6cjfVC7kS8Pj9pCrKSc5txArRyaYGe088shv/FGWH+0Rjx/xPgtsWfsUtS27FkP697E4DDhgrgoc0Q==" - }, - "wrap-ansi": { - "version": "7.0.0", - "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz", - "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==", - "requires": { - "ansi-styles": "^4.0.0", - "string-width": "^4.1.0", - "strip-ansi": "^6.0.0" - } - }, - "y18n": { - "version": "5.0.8", - "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz", - "integrity": "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==" - }, - "yaml": { - "version": "2.1.3", - "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.1.3.tgz", - "integrity": "sha512-AacA8nRULjKMX2DvWvOAdBZMOfQlypSFkjcOcu9FalllIDJ1kvlREzcdIZmidQUqqeMv7jorHjq2HlLv/+c2lg==" - }, - "yargs": { - "version": "17.6.2", - "resolved": "https://registry.npmjs.org/yargs/-/yargs-17.6.2.tgz", - "integrity": "sha512-1/9UrdHjDZc0eOU0HxOHoS78C69UD3JRMvzlJ7S79S2nTaWRA/whGCTV8o9e/N/1Va9YIV7Q4sOxD8VV4pCWOw==", - "requires": { - "cliui": "^8.0.1", - "escalade": "^3.1.1", - "get-caller-file": "^2.0.5", - "require-directory": "^2.1.1", - "string-width": "^4.2.3", - "y18n": "^5.0.5", - "yargs-parser": "^21.1.1" - } - }, - "yargs-parser": { - "version": "21.1.1", - "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-21.1.1.tgz", - "integrity": "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==" - } - } -} diff --git a/scripts/openapi-convert/package.json b/scripts/openapi-convert/package.json deleted file mode 100644 index 96574309e..000000000 --- a/scripts/openapi-convert/package.json +++ /dev/null @@ -1,17 +0,0 @@ -{ - "name": "openapi-convert", - "version": "1.0.0", - "description": "", - "main": "index.js", - "scripts": { - "test": "echo \"Error: no test specified\" && exit 1" - }, - "author": "", - "license": "ISC", - "dependencies": { - "nopt": "^3.0.2", - "replace": "^1.2.2", - "swagger2openapi": "^7.0.8", - "yaml": "^2.1.3" - } -} diff --git a/scripts/openapi-convert/string-fixes.mjs b/scripts/openapi-convert/string-fixes.mjs deleted file mode 100644 index e303550ee..000000000 --- a/scripts/openapi-convert/string-fixes.mjs +++ /dev/null @@ -1,165 +0,0 @@ -"use strict"; -import fs from 'node:fs/promises'; -import path_utils from 'node:path'; -import yaml from 'yaml'; - -const DEFAULT_INDENT = 2; - -// Find the first child field with the given indentation in the given content. -// -// Returns the position at the end of the field's line. -function findYamlChildField(content, min_indent, field_name) { - const min_indent_string = " ".repeat(min_indent); - const field_line = min_indent_string + field_name + ":\n"; - let line_start_idx = 0; - - while (line_start_idx < content.length) { - const content_end = content.slice(line_start_idx); - const line_length = content_end.indexOf("\n") + 1; - const line_end_idx = line_start_idx + line_length; - const line = content_end.slice(0, line_length); - - if (line == field_line) { - // This is the child we are looking for. - return line_end_idx; - } - - if (!line.startsWith(min_indent_string)) { - // We changed the parent so we can't find the child anymore. - return null; - } - - line_start_idx = line_end_idx; - } - - // We didn't find the child. - return null; -} - -// Find the end of the children with the given indentation in the YAML content. -// -// Returns the position at the end of the last child. -function findYamlChildrenEnd(content, min_indent) { - const min_indent_string = " ".repeat(min_indent); - let line_start_idx = 0; - - while (line_start_idx < content.length) { - const content_end = content.slice(line_start_idx); - - if (content_end.startsWith(min_indent_string)) { - const line_length = content_end.indexOf("\n") + 1; - line_start_idx += line_length; - } else { - break; - } - } - - return line_start_idx; -} - -// Convert and replace the YAML in the given content between start and end with JSON. -function replaceYamlWithJson(content, start, end, extra_indent) { - console.log("Processing example", start, end); - const example_yaml = content.slice(start, end); - console.log("```" + example_yaml + "```"); - const example_obj = yaml.parse(example_yaml); - const example_json = JSON.stringify(example_obj, null, DEFAULT_INDENT) + "\n"; - console.log("```" + example_json + "```"); - - // Fix the indentation. - let json_lines = example_json.split("\n"); - // The first and last line don't need the extra indent. - for (let i = 1; i < json_lines.length - 1; i++) { - json_lines[i] = " ".repeat(extra_indent) + json_lines[i]; - } - const indented_example_json = json_lines.join("\n"); - - // Put the opening bracket on the same line as the parent field. - const replace_start = start - 1; - content = content.slice(0, replace_start) + ' ' + indented_example_json + content.slice(end); - - return content; -} - -/// Convert the examples under the given fields in the YAML content to JSON. -function convertExamplesToJson(content, parent_field, example_field) { - const parent_field_regex_string = "( +)" + parent_field + ":\n"; - const parent_field_regex = RegExp(parent_field_regex_string, 'g'); - let match; - let examples = []; - - while ((match = parent_field_regex.exec(content)) !== null) { - console.log("Found parent field", parent_field, match.index); - const indent_capture = match[1]; - const example_field_line_indent = indent_capture.length + DEFAULT_INDENT; - const parent_field_line_end = parent_field_regex.lastIndex; - let content_end = content.slice(parent_field_line_end); - - const example_field_line_end = findYamlChildField(content_end, example_field_line_indent, example_field); - - if (example_field_line_end == null) { - continue; - } - - const example_start = parent_field_line_end + example_field_line_end; - content_end = content.slice(example_start); - console.log("Found example at", example_start); - const example_line_min_indent = example_field_line_indent + DEFAULT_INDENT; - const example_length = findYamlChildrenEnd(content_end, example_line_min_indent); - console.log("Example length", example_length); - - if (example_length > 0) { - examples.push({ - start: example_start, - end: example_start + example_length, - extra_indent: example_field_line_indent, - }) - } - } - - for (const example of examples.reverse()) { - content = replaceYamlWithJson(content, example.start, example.end, example.extra_indent); - } - - return content; -} - -async function applyStringFixesFile(path) { - const relative_separator = path.lastIndexOf('/data/api'); - const short_path = path.slice(relative_separator + 1); - console.log("%s", short_path); - - let content = await fs.readFile(path, "utf-8"); - - // Fix occurrences of `*xx` status codes to `*XX`. - content = content.replaceAll("3xx:", "\"3XX\":"); - content = content.replaceAll("4xx:", "\"4XX\":"); - - // Fix occurrences of `_ref` to `$ref`. - content = content.replaceAll("_ref:", "$ref:"); - - // Fix occurrences of `x-example` to `example`. - content = content.replaceAll("x-example:", "example:"); - - // Convert examples back to JSON. - // Response examples. - content = convertExamplesToJson(content, "response", "value"); - // Schema examples. - content = convertExamplesToJson(content, "schema", "example"); - - await fs.writeFile(path, content); -} - -// Fixes to apply to the string content of the files. -export async function applyStringFixes(path) { - const stat = await fs.lstat(path); - if (stat.isDirectory()) { - const files = await fs.readdir(path); - - for (const file of files) { - await applyStringFixes(path_utils.join(path, file)) - } - } else if (stat.isFile()) { - await applyStringFixesFile(path); - } -} \ No newline at end of file