Better Errors
This commit is contained in:
+309
-234
@@ -29,37 +29,42 @@ paths:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
$ref: "#/components/schemas/MissingFieldResponse"
|
||||
examples:
|
||||
Missing fields:
|
||||
value: { "message": "Missing email" }
|
||||
value:
|
||||
{ "code": "MissingField", "fields": ["email", "password"] }
|
||||
401:
|
||||
description: Invalid credentials.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
$ref: "#/components/schemas/UnauthorizedResponse"
|
||||
examples:
|
||||
Invalid username or password:
|
||||
value: { "message": "Invalid username or password" }
|
||||
value:
|
||||
{
|
||||
"code": "Unauthorized",
|
||||
"message": "Invalid username or password",
|
||||
}
|
||||
404:
|
||||
description: User not found.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
$ref: "#/components/schemas/NotFoundResponse"
|
||||
examples:
|
||||
User not found:
|
||||
value: { "message": "User not found" }
|
||||
value: { "code": "NotFound", "entity": "user" }
|
||||
500:
|
||||
description: Failed.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
$ref: "#/components/schemas/FailedResponse"
|
||||
examples:
|
||||
Failed:
|
||||
value: { "message": "Login failed" }
|
||||
value: { "code": "Failed", "message": "Login failed" }
|
||||
tags:
|
||||
- Login/Logout
|
||||
/logout:
|
||||
@@ -80,221 +85,6 @@ paths:
|
||||
value: true
|
||||
tags:
|
||||
- Login/Logout
|
||||
/register:
|
||||
post:
|
||||
summary: Register
|
||||
description: Register a new user
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/RegisterRequest"
|
||||
responses:
|
||||
200:
|
||||
description: Success
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/UserResponse"
|
||||
400:
|
||||
description: Missing fields or duplicate
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
examples:
|
||||
Missing fields:
|
||||
value: { "message": "Missing email" }
|
||||
Duplicate:
|
||||
value:
|
||||
{
|
||||
"message": "A user with this username or email already exists",
|
||||
}
|
||||
tags:
|
||||
- Register
|
||||
patch:
|
||||
summary: Confirm register
|
||||
description: Confirm a registration
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ConfirmRequest"
|
||||
responses:
|
||||
200:
|
||||
description: Success
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/BooleanResponse"
|
||||
examples:
|
||||
Success:
|
||||
value: true
|
||||
400:
|
||||
description: Missing fields
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
examples:
|
||||
Missing fields:
|
||||
value: { "message": "Missing code" }
|
||||
404:
|
||||
description: User not found
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
examples:
|
||||
User not found:
|
||||
value: { "message": "User not found" }
|
||||
tags:
|
||||
- Register
|
||||
/users:
|
||||
get:
|
||||
summary: List users
|
||||
description: List all users.
|
||||
security:
|
||||
- BasicAuth: []
|
||||
parameters:
|
||||
- in: query
|
||||
name: p
|
||||
schema:
|
||||
type: integer
|
||||
minimum: 0
|
||||
default: 0
|
||||
description: Current page.
|
||||
- in: query
|
||||
name: l
|
||||
schema:
|
||||
type: integer
|
||||
minimum: 0
|
||||
maximum: 30
|
||||
default: 10
|
||||
description: The number of items to return.
|
||||
responses:
|
||||
200:
|
||||
description: Success
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/UserListResponse"
|
||||
tags:
|
||||
- User
|
||||
/user/{id}:
|
||||
get:
|
||||
summary: Get user
|
||||
description: Get user by ID.
|
||||
security:
|
||||
- BasicAuth: [isAdmin]
|
||||
parameters:
|
||||
- name: id
|
||||
in: path
|
||||
description: User ID
|
||||
required: true
|
||||
schema:
|
||||
type: integer
|
||||
format: int14
|
||||
responses:
|
||||
200:
|
||||
description: Success.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/UserResponse"
|
||||
404:
|
||||
description: User not found.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
examples:
|
||||
User not found:
|
||||
value: { "message": "User not found" }
|
||||
tags:
|
||||
- User
|
||||
patch:
|
||||
summary: Update user
|
||||
description:
|
||||
Update user with ID. Fields are updated in order username, password, image. If one fails, subsequent are not updated. <br>
|
||||
Use special ID <code>self</code> to update logged in user. <br>
|
||||
Requires logged in user to have admin permissions for any ID other than <code>self</code>.
|
||||
security:
|
||||
- BasicAuth: []
|
||||
- BasicAuth: [isAdmin]
|
||||
parameters:
|
||||
- name: id
|
||||
in: path
|
||||
description: User ID
|
||||
required: true
|
||||
schema:
|
||||
type: integer
|
||||
format: int14
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/UserUpdateRequest"
|
||||
responses:
|
||||
200:
|
||||
description: Success.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/UserResponse"
|
||||
404:
|
||||
description: User not found.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
examples:
|
||||
User not found:
|
||||
value: { "message": "User not found" }
|
||||
500:
|
||||
description: Update failed.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
examples:
|
||||
Failed username:
|
||||
value: { "message": "Failed to update username" }
|
||||
tags:
|
||||
- User
|
||||
delete:
|
||||
summary: Delete user
|
||||
description: Delete user with ID.
|
||||
security:
|
||||
- BasicAuth: [isAdmin]
|
||||
parameters:
|
||||
- name: id
|
||||
in: path
|
||||
description: User ID
|
||||
required: true
|
||||
schema:
|
||||
type: integer
|
||||
format: int14
|
||||
responses:
|
||||
200:
|
||||
description: Success.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/UserResponse"
|
||||
404:
|
||||
description: User not found.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
examples:
|
||||
User not found:
|
||||
value: { "message": "User not found" }
|
||||
tags:
|
||||
- User
|
||||
/posts:
|
||||
get:
|
||||
summary: List posts
|
||||
@@ -404,16 +194,16 @@ paths:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
$ref: "#/components/schemas/MissingFieldResponse"
|
||||
examples:
|
||||
Missing fields:
|
||||
value: { "message": "Missing content" }
|
||||
value: { "code": "MissingField", "fields": ["content"] }
|
||||
tags:
|
||||
- Post
|
||||
/post/{id}:
|
||||
patch:
|
||||
summary: Update post
|
||||
description: Update post with ID. <br>
|
||||
description: Update post with ID. <br>
|
||||
Requires logged in user to have admin permissions for posts not made by them.
|
||||
security:
|
||||
- BasicAuth: []
|
||||
@@ -438,24 +228,33 @@ paths:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/PostResponse"
|
||||
401:
|
||||
description: Not allowed.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/UnauthorizedResponse"
|
||||
examples:
|
||||
Not allowed:
|
||||
value: { "code": "Unauthorized", "message": "Not allowed" }
|
||||
404:
|
||||
description: Post not found.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
$ref: "#/components/schemas/NotFoundResponse"
|
||||
examples:
|
||||
User not found:
|
||||
value: { "message": "Post not found" }
|
||||
Post not found:
|
||||
value: { "code": "NotFound", "entity": "post" }
|
||||
500:
|
||||
description: Update failed.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
$ref: "#/components/schemas/FailedUpdateResponse"
|
||||
examples:
|
||||
Failed:
|
||||
value: { "message": "Failed to update post" }
|
||||
value: { "code": "FailedUpdate", "fields": ["content"] }
|
||||
tags:
|
||||
- Post
|
||||
delete:
|
||||
@@ -483,12 +282,242 @@ paths:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
$ref: "#/components/schemas/NotFoundResponse"
|
||||
examples:
|
||||
Post not found:
|
||||
value: { "message": "Post not found" }
|
||||
value: { "code": "NotFound", "entity": "post" }
|
||||
tags:
|
||||
- Post
|
||||
/register:
|
||||
post:
|
||||
summary: Register
|
||||
description: Register a new user.
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/RegisterRequest"
|
||||
responses:
|
||||
200:
|
||||
description: Success.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/UserResponse"
|
||||
400:
|
||||
description: Missing fields or duplicate.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
oneOf:
|
||||
- $ref: "#/components/schemas/MissingFieldResponse"
|
||||
- $ref: "#/components/schemas/DuplicateResponse"
|
||||
examples:
|
||||
Missing fields:
|
||||
value:
|
||||
{
|
||||
"code": "MissingField",
|
||||
"fields": ["username", "email", "password"],
|
||||
}
|
||||
Duplicate:
|
||||
value: { "code": "Duplicate", "entity": "user" }
|
||||
404:
|
||||
description: Failed to create
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/FailedResponse"
|
||||
examples:
|
||||
Failed to create:
|
||||
value:
|
||||
{ "code": "Failed", "message": "Failed to create user" }
|
||||
tags:
|
||||
- Register
|
||||
patch:
|
||||
summary: Confirm register
|
||||
description: Confirm a registration.
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ConfirmRequest"
|
||||
responses:
|
||||
200:
|
||||
description: Success.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/UserResponse"
|
||||
400:
|
||||
description: Missing fields.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/MissingFieldResponse"
|
||||
examples:
|
||||
Missing fields:
|
||||
value: { "code": "MissingField", "fields": ["code"] }
|
||||
404:
|
||||
description: User not found.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/NotFoundResponse"
|
||||
examples:
|
||||
User not found:
|
||||
value: { "code": "NotFound", "entity": "user" }
|
||||
tags:
|
||||
- Register
|
||||
/users:
|
||||
get:
|
||||
summary: List users
|
||||
description: List all users.
|
||||
security:
|
||||
- BasicAuth: []
|
||||
parameters:
|
||||
- in: query
|
||||
name: p
|
||||
schema:
|
||||
type: integer
|
||||
minimum: 0
|
||||
default: 0
|
||||
description: Current page.
|
||||
- in: query
|
||||
name: l
|
||||
schema:
|
||||
type: integer
|
||||
minimum: 0
|
||||
maximum: 30
|
||||
default: 10
|
||||
description: The number of items to return.
|
||||
responses:
|
||||
200:
|
||||
description: Success
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/UserListResponse"
|
||||
tags:
|
||||
- User
|
||||
|
||||
/user/{id}:
|
||||
get:
|
||||
summary: Get user
|
||||
description: Get user by ID.
|
||||
security:
|
||||
- BasicAuth: [isAdmin]
|
||||
parameters:
|
||||
- name: id
|
||||
in: path
|
||||
description: User ID
|
||||
required: true
|
||||
schema:
|
||||
type: integer
|
||||
format: int14
|
||||
responses:
|
||||
200:
|
||||
description: Success.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/UserResponse"
|
||||
404:
|
||||
description: User not found.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/NotFoundResponse"
|
||||
examples:
|
||||
User not found:
|
||||
value: { "code": "NotFound", "entity": "user" }
|
||||
tags:
|
||||
- User
|
||||
patch:
|
||||
summary: Update user
|
||||
description: Update user with ID. <br>
|
||||
Use special ID <code>self</code> to update logged in user. <br>
|
||||
Requires logged in user to have admin permissions for any ID other than <code>self</code>.
|
||||
security:
|
||||
- BasicAuth: []
|
||||
- BasicAuth: [isAdmin]
|
||||
parameters:
|
||||
- name: id
|
||||
in: path
|
||||
description: User ID
|
||||
required: true
|
||||
schema:
|
||||
type: integer
|
||||
format: int14
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/UserUpdateRequest"
|
||||
responses:
|
||||
200:
|
||||
description: Success.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/UserResponse"
|
||||
404:
|
||||
description: User not found.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/NotFoundResponse"
|
||||
examples:
|
||||
User not found:
|
||||
value: { "code": "NotFound", "entity": "username" }
|
||||
500:
|
||||
description: Update failed.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/FailedUpdateResponse"
|
||||
examples:
|
||||
Failed username:
|
||||
value:
|
||||
{
|
||||
"code": "FailedUpdate",
|
||||
"fields": ["username", "email", "password"],
|
||||
}
|
||||
tags:
|
||||
- User
|
||||
delete:
|
||||
summary: Delete user
|
||||
description: Delete user with ID.
|
||||
security:
|
||||
- BasicAuth: [isAdmin]
|
||||
parameters:
|
||||
- name: id
|
||||
in: path
|
||||
description: User ID
|
||||
required: true
|
||||
schema:
|
||||
type: integer
|
||||
format: int14
|
||||
responses:
|
||||
200:
|
||||
description: Success.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/UserResponse"
|
||||
404:
|
||||
description: User not found.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/NotFoundResponse"
|
||||
examples:
|
||||
User not found:
|
||||
value: { "code": "NotFound", "entity": "user" }
|
||||
tags:
|
||||
- User
|
||||
|
||||
externalDocs:
|
||||
url: https://khofmann.userpage.fu-berlin.de/phpCourse/exam/api/docs/
|
||||
security: []
|
||||
@@ -498,6 +527,52 @@ components:
|
||||
schemas:
|
||||
BooleanResponse:
|
||||
type: boolean
|
||||
MissingFieldResponse:
|
||||
type: object
|
||||
properties:
|
||||
code:
|
||||
type: MissingField
|
||||
fields:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
NotFoundResponse:
|
||||
type: object
|
||||
properties:
|
||||
code:
|
||||
type: NotFound
|
||||
entity:
|
||||
type: string
|
||||
UnauthorizedResponse:
|
||||
type: object
|
||||
properties:
|
||||
code:
|
||||
type: Unauthorized
|
||||
message:
|
||||
type: string
|
||||
FailedResponse:
|
||||
type: object
|
||||
properties:
|
||||
code:
|
||||
type: Failed
|
||||
message:
|
||||
type: string
|
||||
DuplicateResponse:
|
||||
type: object
|
||||
properties:
|
||||
code:
|
||||
type: Duplicate
|
||||
entity:
|
||||
type: string
|
||||
FailedUpdateResponse:
|
||||
type: object
|
||||
properties:
|
||||
code:
|
||||
type: FailedUpdate
|
||||
fields:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
ErrorResponse:
|
||||
type: object
|
||||
properties:
|
||||
@@ -635,6 +710,6 @@ components:
|
||||
in: header
|
||||
tags:
|
||||
- name: Login/Logout
|
||||
- name: Post
|
||||
- name: Register
|
||||
- name: User
|
||||
- name: Post
|
||||
|
||||
+60
-56
File diff suppressed because one or more lines are too long
Reference in New Issue
Block a user