You've already forked authentication-service
mirror of
https://github.com/matrix-org/matrix-authentication-service.git
synced 2025-07-31 09:24:31 +03:00
Host a Swagger UI both in the static documentation and by the server
This commit is contained in:
Quentin Gliech
24
docs/api/index.html
Normal file
24
docs/api/index.html
Normal file
@ -0,0 +1,24 @@
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<meta name="description" content="SwaggerUI" />
|
||||
<title>API documentation</title>
|
||||
<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui.css" />
|
||||
</head>
|
||||
<body>
|
||||
<div id="swagger-ui"></div>
|
||||
<script src="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui-bundle.js" crossorigin></script>
|
||||
<script>
|
||||
window.onload = () => {
|
||||
window.ui = SwaggerUIBundle({
|
||||
url: './spec.json',
|
||||
dom_id: '#swagger-ui',
|
||||
presets: [
|
||||
SwaggerUIBundle.presets.apis,
|
||||
],
|
||||
});
|
||||
};
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
80
docs/api/oauth2-redirect.html
Normal file
80
docs/api/oauth2-redirect.html
Normal file
@ -0,0 +1,80 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<!-- This is taken from the swagger-ui/dist/oauth2-redirect.html file -->
|
||||
<head>
|
||||
<title>API documentation: OAuth2 Redirect</title>
|
||||
</head>
|
||||
<body>
|
||||
<script>
|
||||
'use strict';
|
||||
function run () {
|
||||
var oauth2 = window.opener.swaggerUIRedirectOauth2;
|
||||
var sentState = oauth2.state;
|
||||
var redirectUrl = oauth2.redirectUrl;
|
||||
var isValid, qp, arr;
|
||||
|
||||
if (/code|token|error/.test(window.location.hash)) {
|
||||
qp = window.location.hash.substring(1).replace('?', '&');
|
||||
} else {
|
||||
qp = location.search.substring(1);
|
||||
}
|
||||
|
||||
arr = qp.split("&");
|
||||
arr.forEach(function (v,i,_arr) { _arr[i] = '"' + v.replace('=', '":"') + '"';});
|
||||
qp = qp ? JSON.parse('{' + arr.join() + '}',
|
||||
function (key, value) {
|
||||
return key === "" ? value : decodeURIComponent(value);
|
||||
}
|
||||
) : {};
|
||||
|
||||
isValid = qp.state === sentState;
|
||||
|
||||
if ((
|
||||
oauth2.auth.schema.get("flow") === "accessCode" ||
|
||||
oauth2.auth.schema.get("flow") === "authorizationCode" ||
|
||||
oauth2.auth.schema.get("flow") === "authorization_code"
|
||||
) && !oauth2.auth.code) {
|
||||
if (!isValid) {
|
||||
oauth2.errCb({
|
||||
authId: oauth2.auth.name,
|
||||
source: "auth",
|
||||
level: "warning",
|
||||
message: "Authorization may be unsafe, passed state was changed in server. The passed state wasn't returned from auth server."
|
||||
});
|
||||
}
|
||||
|
||||
if (qp.code) {
|
||||
delete oauth2.state;
|
||||
oauth2.auth.code = qp.code;
|
||||
oauth2.callback({auth: oauth2.auth, redirectUrl: redirectUrl});
|
||||
} else {
|
||||
let oauthErrorMsg;
|
||||
if (qp.error) {
|
||||
oauthErrorMsg = "["+qp.error+"]: " +
|
||||
(qp.error_description ? qp.error_description+ ". " : "no accessCode received from the server. ") +
|
||||
(qp.error_uri ? "More info: "+qp.error_uri : "");
|
||||
}
|
||||
|
||||
oauth2.errCb({
|
||||
authId: oauth2.auth.name,
|
||||
source: "auth",
|
||||
level: "error",
|
||||
message: oauthErrorMsg || "[Authorization failed]: no accessCode received from the server."
|
||||
});
|
||||
}
|
||||
} else {
|
||||
oauth2.callback({auth: oauth2.auth, token: qp, isValid: isValid, redirectUrl: redirectUrl});
|
||||
}
|
||||
window.close();
|
||||
}
|
||||
|
||||
if (document.readyState !== 'loading') {
|
||||
run();
|
||||
} else {
|
||||
document.addEventListener('DOMContentLoaded', function () {
|
||||
run();
|
||||
});
|
||||
}
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
635
docs/api/spec.json
Normal file
635
docs/api/spec.json
Normal file
@ -0,0 +1,635 @@
|
||||
{
|
||||
"openapi": "3.1.0",
|
||||
"info": {
|
||||
"title": "Matrix Authentication Service admin API",
|
||||
"version": ""
|
||||
},
|
||||
"servers": [
|
||||
{
|
||||
"url": "{base}",
|
||||
"variables": {
|
||||
"base": {
|
||||
"default": "/",
|
||||
"description": null
|
||||
}
|
||||
}
|
||||
}
|
||||
],
|
||||
"paths": {
|
||||
"/api/admin/v1/users": {
|
||||
"get": {
|
||||
"description": "List users",
|
||||
"parameters": [
|
||||
{
|
||||
"in": "query",
|
||||
"name": "page[before]",
|
||||
"description": "Retrieve the items before the given ID",
|
||||
"schema": {
|
||||
"description": "Retrieve the items before the given ID",
|
||||
"type": [
|
||||
"string",
|
||||
"null"
|
||||
]
|
||||
},
|
||||
"style": "form"
|
||||
},
|
||||
{
|
||||
"in": "query",
|
||||
"name": "page[after]",
|
||||
"description": "Retrieve the items after the given ID",
|
||||
"schema": {
|
||||
"description": "Retrieve the items after the given ID",
|
||||
"type": [
|
||||
"string",
|
||||
"null"
|
||||
]
|
||||
},
|
||||
"style": "form"
|
||||
},
|
||||
{
|
||||
"in": "query",
|
||||
"name": "page[first]",
|
||||
"description": "Retrieve the first N items",
|
||||
"schema": {
|
||||
"description": "Retrieve the first N items",
|
||||
"type": [
|
||||
"integer",
|
||||
"null"
|
||||
],
|
||||
"format": "uint",
|
||||
"minimum": 1.0
|
||||
},
|
||||
"style": "form"
|
||||
},
|
||||
{
|
||||
"in": "query",
|
||||
"name": "page[last]",
|
||||
"description": "Retrieve the last N items",
|
||||
"schema": {
|
||||
"description": "Retrieve the last N items",
|
||||
"type": [
|
||||
"integer",
|
||||
"null"
|
||||
],
|
||||
"format": "uint",
|
||||
"minimum": 1.0
|
||||
},
|
||||
"style": "form"
|
||||
},
|
||||
{
|
||||
"in": "query",
|
||||
"name": "filter[can_request_admin]",
|
||||
"schema": {
|
||||
"type": [
|
||||
"boolean",
|
||||
"null"
|
||||
]
|
||||
},
|
||||
"style": "form"
|
||||
},
|
||||
{
|
||||
"in": "query",
|
||||
"name": "filter[status]",
|
||||
"schema": {
|
||||
"anyOf": [
|
||||
{
|
||||
"$ref": "#/components/schemas/UserStatus"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
]
|
||||
},
|
||||
"style": "form"
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Paginated response of users",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/PaginatedResponse_for_User"
|
||||
},
|
||||
"example": {
|
||||
"meta": {
|
||||
"count": 42
|
||||
},
|
||||
"data": [
|
||||
{
|
||||
"type": "user",
|
||||
"id": "01040G2081040G2081040G2081",
|
||||
"attributes": {
|
||||
"username": "alice",
|
||||
"created_at": "1970-01-01T00:00:00Z",
|
||||
"locked_at": null,
|
||||
"can_request_admin": false
|
||||
},
|
||||
"links": {
|
||||
"self": "/api/admin/v1/users/01040G2081040G2081040G2081"
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "user",
|
||||
"id": "02081040G2081040G2081040G2",
|
||||
"attributes": {
|
||||
"username": "bob",
|
||||
"created_at": "1970-01-01T00:00:00Z",
|
||||
"locked_at": null,
|
||||
"can_request_admin": true
|
||||
},
|
||||
"links": {
|
||||
"self": "/api/admin/v1/users/02081040G2081040G2081040G2"
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "user",
|
||||
"id": "030C1G60R30C1G60R30C1G60R3",
|
||||
"attributes": {
|
||||
"username": "charlie",
|
||||
"created_at": "1970-01-01T00:00:00Z",
|
||||
"locked_at": "1970-01-01T00:00:00Z",
|
||||
"can_request_admin": false
|
||||
},
|
||||
"links": {
|
||||
"self": "/api/admin/v1/users/030C1G60R30C1G60R30C1G60R3"
|
||||
}
|
||||
}
|
||||
],
|
||||
"links": {
|
||||
"self": "/api/admin/v1/users?page[first]=3",
|
||||
"first": "/api/admin/v1/users?page[first]=3",
|
||||
"last": "/api/admin/v1/users?page[last]=3",
|
||||
"next": "/api/admin/v1/users?page[after]=030C1G60R30C1G60R30C1G60R3&page[first]=3"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/admin/v1/users/{id}": {
|
||||
"get": {
|
||||
"description": "Get a user",
|
||||
"parameters": [
|
||||
{
|
||||
"in": "path",
|
||||
"name": "id",
|
||||
"description": "A ULID as per https://github.com/ulid/spec",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"title": "ULID",
|
||||
"description": "A ULID as per https://github.com/ulid/spec",
|
||||
"type": "string",
|
||||
"pattern": "^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
|
||||
},
|
||||
"style": "simple"
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "User was found",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/SingleResponse_for_User"
|
||||
},
|
||||
"example": {
|
||||
"data": {
|
||||
"type": "user",
|
||||
"id": "01040G2081040G2081040G2081",
|
||||
"attributes": {
|
||||
"username": "alice",
|
||||
"created_at": "1970-01-01T00:00:00Z",
|
||||
"locked_at": null,
|
||||
"can_request_admin": false
|
||||
},
|
||||
"links": {
|
||||
"self": "/api/admin/v1/users/01040G2081040G2081040G2081"
|
||||
}
|
||||
},
|
||||
"links": {
|
||||
"self": "/api/admin/v1/users/01040G2081040G2081040G2081"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "User was not found",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
},
|
||||
"example": {
|
||||
"errors": [
|
||||
{
|
||||
"title": "User ID 00000000000000000000000000 not found"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/admin/v1/users/by-username/{username}": {
|
||||
"get": {
|
||||
"description": "Get a user by its username (localpart)",
|
||||
"parameters": [
|
||||
{
|
||||
"in": "path",
|
||||
"name": "username",
|
||||
"description": "The username (localpart) of the user to get",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"description": "The username (localpart) of the user to get",
|
||||
"type": "string"
|
||||
},
|
||||
"style": "simple"
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "User was found",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/SingleResponse_for_User"
|
||||
},
|
||||
"example": {
|
||||
"data": {
|
||||
"type": "user",
|
||||
"id": "01040G2081040G2081040G2081",
|
||||
"attributes": {
|
||||
"username": "alice",
|
||||
"created_at": "1970-01-01T00:00:00Z",
|
||||
"locked_at": null,
|
||||
"can_request_admin": false
|
||||
},
|
||||
"links": {
|
||||
"self": "/api/admin/v1/users/01040G2081040G2081040G2081"
|
||||
}
|
||||
},
|
||||
"links": {
|
||||
"self": "/api/admin/v1/users/by-username/alice"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "User was not found",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/ErrorResponse"
|
||||
},
|
||||
"example": {
|
||||
"errors": [
|
||||
{
|
||||
"title": "User with username \"alice\" not found"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"components": {
|
||||
"securitySchemes": {
|
||||
"oauth2": {
|
||||
"type": "oauth2",
|
||||
"flows": {
|
||||
"clientCredentials": {
|
||||
"refreshUrl": "/oauth2/token",
|
||||
"tokenUrl": "/oauth2/token",
|
||||
"scopes": {
|
||||
"urn:mas:admin": "Grant access to the admin API"
|
||||
}
|
||||
},
|
||||
"authorizationCode": {
|
||||
"authorizationUrl": "/authorize",
|
||||
"tokenUrl": "/oauth2/token",
|
||||
"refreshUrl": "/oauth2/token",
|
||||
"scopes": {
|
||||
"urn:mas:admin": "Grant access to the admin API"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"schemas": {
|
||||
"PaginationParams": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"page[before]": {
|
||||
"description": "Retrieve the items before the given ID",
|
||||
"type": [
|
||||
"string",
|
||||
"null"
|
||||
]
|
||||
},
|
||||
"page[after]": {
|
||||
"description": "Retrieve the items after the given ID",
|
||||
"type": [
|
||||
"string",
|
||||
"null"
|
||||
]
|
||||
},
|
||||
"page[first]": {
|
||||
"description": "Retrieve the first N items",
|
||||
"type": [
|
||||
"integer",
|
||||
"null"
|
||||
],
|
||||
"format": "uint",
|
||||
"minimum": 1.0
|
||||
},
|
||||
"page[last]": {
|
||||
"description": "Retrieve the last N items",
|
||||
"type": [
|
||||
"integer",
|
||||
"null"
|
||||
],
|
||||
"format": "uint",
|
||||
"minimum": 1.0
|
||||
}
|
||||
}
|
||||
},
|
||||
"FilterParams": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"filter[can_request_admin]": {
|
||||
"type": [
|
||||
"boolean",
|
||||
"null"
|
||||
]
|
||||
},
|
||||
"filter[status]": {
|
||||
"anyOf": [
|
||||
{
|
||||
"$ref": "#/components/schemas/UserStatus"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
"UserStatus": {
|
||||
"oneOf": [
|
||||
{
|
||||
"description": "The user is active",
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"active"
|
||||
]
|
||||
},
|
||||
{
|
||||
"description": "The user is locked",
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"locked"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
"PaginatedResponse_for_User": {
|
||||
"description": "A top-level response with a page of resources",
|
||||
"type": "object",
|
||||
"required": [
|
||||
"data",
|
||||
"links",
|
||||
"meta"
|
||||
],
|
||||
"properties": {
|
||||
"meta": {
|
||||
"description": "Response metadata",
|
||||
"$ref": "#/components/schemas/PaginationMeta"
|
||||
},
|
||||
"data": {
|
||||
"description": "The list of resources",
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/components/schemas/SingleResource_for_User"
|
||||
}
|
||||
},
|
||||
"links": {
|
||||
"description": "Related links",
|
||||
"$ref": "#/components/schemas/PaginationLinks"
|
||||
}
|
||||
}
|
||||
},
|
||||
"PaginationMeta": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"count"
|
||||
],
|
||||
"properties": {
|
||||
"count": {
|
||||
"description": "The total number of results",
|
||||
"type": "integer",
|
||||
"format": "uint",
|
||||
"minimum": 0.0
|
||||
}
|
||||
}
|
||||
},
|
||||
"SingleResource_for_User": {
|
||||
"description": "A single resource, with its type, ID, attributes and related links",
|
||||
"type": "object",
|
||||
"required": [
|
||||
"attributes",
|
||||
"id",
|
||||
"links",
|
||||
"type"
|
||||
],
|
||||
"properties": {
|
||||
"type": {
|
||||
"description": "The type of the resource",
|
||||
"type": "string"
|
||||
},
|
||||
"id": {
|
||||
"description": "The ID of the resource",
|
||||
"type": "string"
|
||||
},
|
||||
"attributes": {
|
||||
"description": "The attributes of the resource",
|
||||
"$ref": "#/components/schemas/User"
|
||||
},
|
||||
"links": {
|
||||
"description": "Related links",
|
||||
"$ref": "#/components/schemas/SelfLinks"
|
||||
}
|
||||
}
|
||||
},
|
||||
"User": {
|
||||
"description": "A user",
|
||||
"type": "object",
|
||||
"required": [
|
||||
"can_request_admin",
|
||||
"created_at",
|
||||
"username"
|
||||
],
|
||||
"properties": {
|
||||
"username": {
|
||||
"description": "The username (localpart) of the user",
|
||||
"type": "string"
|
||||
},
|
||||
"created_at": {
|
||||
"description": "When the user was created",
|
||||
"type": "string",
|
||||
"format": "date-time"
|
||||
},
|
||||
"locked_at": {
|
||||
"description": "When the user was locked. If null, the user is not locked.",
|
||||
"type": [
|
||||
"string",
|
||||
"null"
|
||||
],
|
||||
"format": "date-time"
|
||||
},
|
||||
"can_request_admin": {
|
||||
"description": "Whether the user can request admin privileges.",
|
||||
"type": "boolean"
|
||||
}
|
||||
}
|
||||
},
|
||||
"SelfLinks": {
|
||||
"description": "Related links",
|
||||
"type": "object",
|
||||
"required": [
|
||||
"self"
|
||||
],
|
||||
"properties": {
|
||||
"self": {
|
||||
"description": "The canonical link to the current resource",
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"PaginationLinks": {
|
||||
"description": "Related links",
|
||||
"type": "object",
|
||||
"required": [
|
||||
"first",
|
||||
"last",
|
||||
"self"
|
||||
],
|
||||
"properties": {
|
||||
"self": {
|
||||
"description": "The canonical link to the current page",
|
||||
"type": "string"
|
||||
},
|
||||
"first": {
|
||||
"description": "The link to the first page of results",
|
||||
"type": "string"
|
||||
},
|
||||
"last": {
|
||||
"description": "The link to the last page of results",
|
||||
"type": "string"
|
||||
},
|
||||
"next": {
|
||||
"description": "The link to the next page of results\n\nOnly present if there is a next page",
|
||||
"type": [
|
||||
"string",
|
||||
"null"
|
||||
]
|
||||
},
|
||||
"prev": {
|
||||
"description": "The link to the previous page of results\n\nOnly present if there is a previous page",
|
||||
"type": [
|
||||
"string",
|
||||
"null"
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
"ErrorResponse": {
|
||||
"description": "A top-level response with a list of errors",
|
||||
"type": "object",
|
||||
"required": [
|
||||
"errors"
|
||||
],
|
||||
"properties": {
|
||||
"errors": {
|
||||
"description": "The list of errors",
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/components/schemas/Error"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"Error": {
|
||||
"description": "A single error",
|
||||
"type": "object",
|
||||
"required": [
|
||||
"title"
|
||||
],
|
||||
"properties": {
|
||||
"title": {
|
||||
"description": "A human-readable title for the error",
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"UlidInPath": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"id"
|
||||
],
|
||||
"properties": {
|
||||
"id": {
|
||||
"title": "ULID",
|
||||
"description": "A ULID as per https://github.com/ulid/spec",
|
||||
"type": "string",
|
||||
"pattern": "^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
|
||||
}
|
||||
}
|
||||
},
|
||||
"SingleResponse_for_User": {
|
||||
"description": "A top-level response with a single resource",
|
||||
"type": "object",
|
||||
"required": [
|
||||
"data",
|
||||
"links"
|
||||
],
|
||||
"properties": {
|
||||
"data": {
|
||||
"$ref": "#/components/schemas/SingleResource_for_User"
|
||||
},
|
||||
"links": {
|
||||
"$ref": "#/components/schemas/SelfLinks"
|
||||
}
|
||||
}
|
||||
},
|
||||
"UsernamePathParam": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"username"
|
||||
],
|
||||
"properties": {
|
||||
"username": {
|
||||
"description": "The username (localpart) of the user to get",
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"security": [
|
||||
{
|
||||
"oauth2": [
|
||||
"urn:mas:admin"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
Reference in New Issue
Block a user