feat: declare API errors and authentication with developer tooling
This commit is contained in:
@@ -1,7 +1,8 @@
|
||||
{
|
||||
"components": {
|
||||
"securitySchemes": {
|
||||
"bearerAuth": {
|
||||
"AdminAuth": {
|
||||
"description": "Use an administrator token for writes, or a read-only token for GET requests",
|
||||
"scheme": "bearer",
|
||||
"type": "http"
|
||||
}
|
||||
@@ -128,6 +129,16 @@
|
||||
"400": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"examples": {
|
||||
"InvalidPage": {
|
||||
"summary": "invalid pagination",
|
||||
"value": {
|
||||
"code": "INVALID_PAGE",
|
||||
"message": "invalid pagination",
|
||||
"requestId": "exampleRequest"
|
||||
}
|
||||
}
|
||||
},
|
||||
"schema": {
|
||||
"properties": {
|
||||
"code": {
|
||||
@@ -148,7 +159,42 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "Error"
|
||||
"description": "INVALID_PAGE: invalid pagination"
|
||||
},
|
||||
"401": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"examples": {
|
||||
"Unauthenticated": {
|
||||
"summary": "authentication required",
|
||||
"value": {
|
||||
"code": "UNAUTHENTICATED",
|
||||
"message": "authentication required",
|
||||
"requestId": "exampleRequest"
|
||||
}
|
||||
}
|
||||
},
|
||||
"schema": {
|
||||
"properties": {
|
||||
"code": {
|
||||
"type": "string"
|
||||
},
|
||||
"message": {
|
||||
"type": "string"
|
||||
},
|
||||
"requestId": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"code",
|
||||
"message"
|
||||
],
|
||||
"type": "object"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "UNAUTHENTICATED: authentication required"
|
||||
},
|
||||
"413": {
|
||||
"content": {
|
||||
@@ -251,12 +297,25 @@
|
||||
"description": "Error"
|
||||
}
|
||||
},
|
||||
"security": [
|
||||
{
|
||||
"AdminAuth": []
|
||||
}
|
||||
],
|
||||
"summary": "",
|
||||
"tags": [
|
||||
"user"
|
||||
],
|
||||
"x-omni-errors": [
|
||||
"Unauthenticated",
|
||||
"InvalidPage"
|
||||
],
|
||||
"x-omni-middleware": [
|
||||
"Auth"
|
||||
]
|
||||
},
|
||||
"post": {
|
||||
"description": "Normalizes the email, then commits user data and audit in one transaction",
|
||||
"operationId": "user_CreateUser",
|
||||
"requestBody": {
|
||||
"content": {
|
||||
@@ -345,6 +404,16 @@
|
||||
"400": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"examples": {
|
||||
"InvalidUser": {
|
||||
"summary": "invalid user",
|
||||
"value": {
|
||||
"code": "INVALID_USER",
|
||||
"message": "invalid user",
|
||||
"requestId": "exampleRequest"
|
||||
}
|
||||
}
|
||||
},
|
||||
"schema": {
|
||||
"properties": {
|
||||
"code": {
|
||||
@@ -365,7 +434,118 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "Error"
|
||||
"description": "INVALID_USER: invalid user"
|
||||
},
|
||||
"401": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"examples": {
|
||||
"Unauthenticated": {
|
||||
"summary": "authentication required",
|
||||
"value": {
|
||||
"code": "UNAUTHENTICATED",
|
||||
"message": "authentication required",
|
||||
"requestId": "exampleRequest"
|
||||
}
|
||||
}
|
||||
},
|
||||
"schema": {
|
||||
"properties": {
|
||||
"code": {
|
||||
"type": "string"
|
||||
},
|
||||
"message": {
|
||||
"type": "string"
|
||||
},
|
||||
"requestId": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"code",
|
||||
"message"
|
||||
],
|
||||
"type": "object"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "UNAUTHENTICATED: authentication required"
|
||||
},
|
||||
"403": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"examples": {
|
||||
"Forbidden": {
|
||||
"summary": "permission denied",
|
||||
"value": {
|
||||
"code": "FORBIDDEN",
|
||||
"message": "permission denied",
|
||||
"requestId": "exampleRequest"
|
||||
}
|
||||
}
|
||||
},
|
||||
"schema": {
|
||||
"properties": {
|
||||
"code": {
|
||||
"enum": [
|
||||
"FORBIDDEN"
|
||||
],
|
||||
"type": "string"
|
||||
},
|
||||
"message": {
|
||||
"type": "string"
|
||||
},
|
||||
"requestId": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"code",
|
||||
"message"
|
||||
],
|
||||
"type": "object"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "FORBIDDEN: permission denied"
|
||||
},
|
||||
"409": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"examples": {
|
||||
"EmailTaken": {
|
||||
"summary": "email already in use",
|
||||
"value": {
|
||||
"code": "EMAIL_TAKEN",
|
||||
"message": "email already in use",
|
||||
"requestId": "exampleRequest"
|
||||
}
|
||||
}
|
||||
},
|
||||
"schema": {
|
||||
"properties": {
|
||||
"code": {
|
||||
"enum": [
|
||||
"EMAIL_TAKEN"
|
||||
],
|
||||
"type": "string"
|
||||
},
|
||||
"message": {
|
||||
"type": "string"
|
||||
},
|
||||
"requestId": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"code",
|
||||
"message"
|
||||
],
|
||||
"type": "object"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "EMAIL_TAKEN: email already in use"
|
||||
},
|
||||
"413": {
|
||||
"content": {
|
||||
@@ -468,7 +648,21 @@
|
||||
"description": "Error"
|
||||
}
|
||||
},
|
||||
"summary": "",
|
||||
"security": [
|
||||
{
|
||||
"AdminAuth": []
|
||||
}
|
||||
],
|
||||
"summary": "Create a user",
|
||||
"tags": [
|
||||
"users"
|
||||
],
|
||||
"x-omni-errors": [
|
||||
"Unauthenticated",
|
||||
"Forbidden",
|
||||
"InvalidUser",
|
||||
"EmailTaken"
|
||||
],
|
||||
"x-omni-middleware": [
|
||||
"Auth"
|
||||
]
|
||||
@@ -519,6 +713,117 @@
|
||||
},
|
||||
"description": "Error"
|
||||
},
|
||||
"401": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"examples": {
|
||||
"Unauthenticated": {
|
||||
"summary": "authentication required",
|
||||
"value": {
|
||||
"code": "UNAUTHENTICATED",
|
||||
"message": "authentication required",
|
||||
"requestId": "exampleRequest"
|
||||
}
|
||||
}
|
||||
},
|
||||
"schema": {
|
||||
"properties": {
|
||||
"code": {
|
||||
"type": "string"
|
||||
},
|
||||
"message": {
|
||||
"type": "string"
|
||||
},
|
||||
"requestId": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"code",
|
||||
"message"
|
||||
],
|
||||
"type": "object"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "UNAUTHENTICATED: authentication required"
|
||||
},
|
||||
"403": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"examples": {
|
||||
"Forbidden": {
|
||||
"summary": "permission denied",
|
||||
"value": {
|
||||
"code": "FORBIDDEN",
|
||||
"message": "permission denied",
|
||||
"requestId": "exampleRequest"
|
||||
}
|
||||
}
|
||||
},
|
||||
"schema": {
|
||||
"properties": {
|
||||
"code": {
|
||||
"enum": [
|
||||
"FORBIDDEN"
|
||||
],
|
||||
"type": "string"
|
||||
},
|
||||
"message": {
|
||||
"type": "string"
|
||||
},
|
||||
"requestId": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"code",
|
||||
"message"
|
||||
],
|
||||
"type": "object"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "FORBIDDEN: permission denied"
|
||||
},
|
||||
"404": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"examples": {
|
||||
"UserNotFound": {
|
||||
"summary": "user not found",
|
||||
"value": {
|
||||
"code": "USER_NOT_FOUND",
|
||||
"message": "user not found",
|
||||
"requestId": "exampleRequest"
|
||||
}
|
||||
}
|
||||
},
|
||||
"schema": {
|
||||
"properties": {
|
||||
"code": {
|
||||
"enum": [
|
||||
"USER_NOT_FOUND"
|
||||
],
|
||||
"type": "string"
|
||||
},
|
||||
"message": {
|
||||
"type": "string"
|
||||
},
|
||||
"requestId": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"code",
|
||||
"message"
|
||||
],
|
||||
"type": "object"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "USER_NOT_FOUND: user not found"
|
||||
},
|
||||
"413": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
@@ -620,7 +925,20 @@
|
||||
"description": "Error"
|
||||
}
|
||||
},
|
||||
"security": [
|
||||
{
|
||||
"AdminAuth": []
|
||||
}
|
||||
],
|
||||
"summary": "",
|
||||
"tags": [
|
||||
"user"
|
||||
],
|
||||
"x-omni-errors": [
|
||||
"Unauthenticated",
|
||||
"Forbidden",
|
||||
"UserNotFound"
|
||||
],
|
||||
"x-omni-middleware": [
|
||||
"Auth"
|
||||
]
|
||||
@@ -721,6 +1039,79 @@
|
||||
},
|
||||
"description": "Error"
|
||||
},
|
||||
"401": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"examples": {
|
||||
"Unauthenticated": {
|
||||
"summary": "authentication required",
|
||||
"value": {
|
||||
"code": "UNAUTHENTICATED",
|
||||
"message": "authentication required",
|
||||
"requestId": "exampleRequest"
|
||||
}
|
||||
}
|
||||
},
|
||||
"schema": {
|
||||
"properties": {
|
||||
"code": {
|
||||
"type": "string"
|
||||
},
|
||||
"message": {
|
||||
"type": "string"
|
||||
},
|
||||
"requestId": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"code",
|
||||
"message"
|
||||
],
|
||||
"type": "object"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "UNAUTHENTICATED: authentication required"
|
||||
},
|
||||
"404": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"examples": {
|
||||
"UserNotFound": {
|
||||
"summary": "user not found",
|
||||
"value": {
|
||||
"code": "USER_NOT_FOUND",
|
||||
"message": "user not found",
|
||||
"requestId": "exampleRequest"
|
||||
}
|
||||
}
|
||||
},
|
||||
"schema": {
|
||||
"properties": {
|
||||
"code": {
|
||||
"enum": [
|
||||
"USER_NOT_FOUND"
|
||||
],
|
||||
"type": "string"
|
||||
},
|
||||
"message": {
|
||||
"type": "string"
|
||||
},
|
||||
"requestId": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"code",
|
||||
"message"
|
||||
],
|
||||
"type": "object"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "USER_NOT_FOUND: user not found"
|
||||
},
|
||||
"413": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
@@ -822,7 +1213,19 @@
|
||||
"description": "Error"
|
||||
}
|
||||
},
|
||||
"security": [
|
||||
{
|
||||
"AdminAuth": []
|
||||
}
|
||||
],
|
||||
"summary": "",
|
||||
"tags": [
|
||||
"user"
|
||||
],
|
||||
"x-omni-errors": [
|
||||
"Unauthenticated",
|
||||
"UserNotFound"
|
||||
],
|
||||
"x-omni-middleware": [
|
||||
"Auth"
|
||||
]
|
||||
@@ -929,6 +1332,16 @@
|
||||
"400": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"examples": {
|
||||
"InvalidUser": {
|
||||
"summary": "invalid user",
|
||||
"value": {
|
||||
"code": "INVALID_USER",
|
||||
"message": "invalid user",
|
||||
"requestId": "exampleRequest"
|
||||
}
|
||||
}
|
||||
},
|
||||
"schema": {
|
||||
"properties": {
|
||||
"code": {
|
||||
@@ -949,7 +1362,156 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "Error"
|
||||
"description": "INVALID_USER: invalid user"
|
||||
},
|
||||
"401": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"examples": {
|
||||
"Unauthenticated": {
|
||||
"summary": "authentication required",
|
||||
"value": {
|
||||
"code": "UNAUTHENTICATED",
|
||||
"message": "authentication required",
|
||||
"requestId": "exampleRequest"
|
||||
}
|
||||
}
|
||||
},
|
||||
"schema": {
|
||||
"properties": {
|
||||
"code": {
|
||||
"type": "string"
|
||||
},
|
||||
"message": {
|
||||
"type": "string"
|
||||
},
|
||||
"requestId": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"code",
|
||||
"message"
|
||||
],
|
||||
"type": "object"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "UNAUTHENTICATED: authentication required"
|
||||
},
|
||||
"403": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"examples": {
|
||||
"Forbidden": {
|
||||
"summary": "permission denied",
|
||||
"value": {
|
||||
"code": "FORBIDDEN",
|
||||
"message": "permission denied",
|
||||
"requestId": "exampleRequest"
|
||||
}
|
||||
}
|
||||
},
|
||||
"schema": {
|
||||
"properties": {
|
||||
"code": {
|
||||
"enum": [
|
||||
"FORBIDDEN"
|
||||
],
|
||||
"type": "string"
|
||||
},
|
||||
"message": {
|
||||
"type": "string"
|
||||
},
|
||||
"requestId": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"code",
|
||||
"message"
|
||||
],
|
||||
"type": "object"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "FORBIDDEN: permission denied"
|
||||
},
|
||||
"404": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"examples": {
|
||||
"UserNotFound": {
|
||||
"summary": "user not found",
|
||||
"value": {
|
||||
"code": "USER_NOT_FOUND",
|
||||
"message": "user not found",
|
||||
"requestId": "exampleRequest"
|
||||
}
|
||||
}
|
||||
},
|
||||
"schema": {
|
||||
"properties": {
|
||||
"code": {
|
||||
"enum": [
|
||||
"USER_NOT_FOUND"
|
||||
],
|
||||
"type": "string"
|
||||
},
|
||||
"message": {
|
||||
"type": "string"
|
||||
},
|
||||
"requestId": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"code",
|
||||
"message"
|
||||
],
|
||||
"type": "object"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "USER_NOT_FOUND: user not found"
|
||||
},
|
||||
"409": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"examples": {
|
||||
"EmailTaken": {
|
||||
"summary": "email already in use",
|
||||
"value": {
|
||||
"code": "EMAIL_TAKEN",
|
||||
"message": "email already in use",
|
||||
"requestId": "exampleRequest"
|
||||
}
|
||||
}
|
||||
},
|
||||
"schema": {
|
||||
"properties": {
|
||||
"code": {
|
||||
"enum": [
|
||||
"EMAIL_TAKEN"
|
||||
],
|
||||
"type": "string"
|
||||
},
|
||||
"message": {
|
||||
"type": "string"
|
||||
},
|
||||
"requestId": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"code",
|
||||
"message"
|
||||
],
|
||||
"type": "object"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "EMAIL_TAKEN: email already in use"
|
||||
},
|
||||
"413": {
|
||||
"content": {
|
||||
@@ -1052,7 +1614,22 @@
|
||||
"description": "Error"
|
||||
}
|
||||
},
|
||||
"security": [
|
||||
{
|
||||
"AdminAuth": []
|
||||
}
|
||||
],
|
||||
"summary": "",
|
||||
"tags": [
|
||||
"user"
|
||||
],
|
||||
"x-omni-errors": [
|
||||
"Unauthenticated",
|
||||
"Forbidden",
|
||||
"InvalidUser",
|
||||
"UserNotFound",
|
||||
"EmailTaken"
|
||||
],
|
||||
"x-omni-middleware": [
|
||||
"Auth"
|
||||
]
|
||||
@@ -1138,6 +1715,117 @@
|
||||
},
|
||||
"description": "Error"
|
||||
},
|
||||
"401": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"examples": {
|
||||
"Unauthenticated": {
|
||||
"summary": "authentication required",
|
||||
"value": {
|
||||
"code": "UNAUTHENTICATED",
|
||||
"message": "authentication required",
|
||||
"requestId": "exampleRequest"
|
||||
}
|
||||
}
|
||||
},
|
||||
"schema": {
|
||||
"properties": {
|
||||
"code": {
|
||||
"type": "string"
|
||||
},
|
||||
"message": {
|
||||
"type": "string"
|
||||
},
|
||||
"requestId": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"code",
|
||||
"message"
|
||||
],
|
||||
"type": "object"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "UNAUTHENTICATED: authentication required"
|
||||
},
|
||||
"403": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"examples": {
|
||||
"Forbidden": {
|
||||
"summary": "permission denied",
|
||||
"value": {
|
||||
"code": "FORBIDDEN",
|
||||
"message": "permission denied",
|
||||
"requestId": "exampleRequest"
|
||||
}
|
||||
}
|
||||
},
|
||||
"schema": {
|
||||
"properties": {
|
||||
"code": {
|
||||
"enum": [
|
||||
"FORBIDDEN"
|
||||
],
|
||||
"type": "string"
|
||||
},
|
||||
"message": {
|
||||
"type": "string"
|
||||
},
|
||||
"requestId": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"code",
|
||||
"message"
|
||||
],
|
||||
"type": "object"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "FORBIDDEN: permission denied"
|
||||
},
|
||||
"404": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"examples": {
|
||||
"UserNotFound": {
|
||||
"summary": "user not found",
|
||||
"value": {
|
||||
"code": "USER_NOT_FOUND",
|
||||
"message": "user not found",
|
||||
"requestId": "exampleRequest"
|
||||
}
|
||||
}
|
||||
},
|
||||
"schema": {
|
||||
"properties": {
|
||||
"code": {
|
||||
"enum": [
|
||||
"USER_NOT_FOUND"
|
||||
],
|
||||
"type": "string"
|
||||
},
|
||||
"message": {
|
||||
"type": "string"
|
||||
},
|
||||
"requestId": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"code",
|
||||
"message"
|
||||
],
|
||||
"type": "object"
|
||||
}
|
||||
}
|
||||
},
|
||||
"description": "USER_NOT_FOUND: user not found"
|
||||
},
|
||||
"413": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
@@ -1239,11 +1927,62 @@
|
||||
"description": "Error"
|
||||
}
|
||||
},
|
||||
"security": [
|
||||
{
|
||||
"AdminAuth": []
|
||||
}
|
||||
],
|
||||
"summary": "Export one user as a private text object with a short-lived download link",
|
||||
"tags": [
|
||||
"user"
|
||||
],
|
||||
"x-omni-errors": [
|
||||
"Unauthenticated",
|
||||
"Forbidden",
|
||||
"UserNotFound"
|
||||
],
|
||||
"x-omni-middleware": [
|
||||
"Auth"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"x-omni-errors": [
|
||||
{
|
||||
"name": "Unauthenticated",
|
||||
"status": 401,
|
||||
"code": "UNAUTHENTICATED",
|
||||
"message": "authentication required"
|
||||
},
|
||||
{
|
||||
"name": "Forbidden",
|
||||
"status": 403,
|
||||
"code": "FORBIDDEN",
|
||||
"message": "permission denied"
|
||||
},
|
||||
{
|
||||
"name": "UserNotFound",
|
||||
"status": 404,
|
||||
"code": "USER_NOT_FOUND",
|
||||
"message": "user not found"
|
||||
},
|
||||
{
|
||||
"name": "EmailTaken",
|
||||
"status": 409,
|
||||
"code": "EMAIL_TAKEN",
|
||||
"message": "email already in use"
|
||||
},
|
||||
{
|
||||
"name": "InvalidUser",
|
||||
"status": 400,
|
||||
"code": "INVALID_USER",
|
||||
"message": "invalid user"
|
||||
},
|
||||
{
|
||||
"name": "InvalidPage",
|
||||
"status": 400,
|
||||
"code": "INVALID_PAGE",
|
||||
"message": "invalid pagination"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user