megahunt.test/public/openapi.yml

559 lines
15 KiB
YAML

info:
title: Parameters API
version: '1.0'
openapi: '3.0.1'
tags:
- name: Users
- name: Private routes
description: Accessible only to authenticated users
paths:
/api/users/register:
put:
summary: Create new user
description: Create new user
tags:
- Users
requestBody:
content:
application/json:
schema:
type: object
properties:
last_name:
type: string
name:
type: string
middle_name:
type: string
email:
type: string
phone:
type: string
password:
type: string
example: 'strong_password123'
responses:
200:
description: |-
User registered successfully.
There is no response body
400:
description: |-
There is an issue with your request.
Response string is an enum:
| key | val |
| --- | --- |
| `email_taken` | the email is already registered. user is expected to either log in or reset password |
This error also might be sent by laravel if your body is corrupted
content:
application/json:
schema:
type: string
example: 'bad_password'
422:
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
/api/users/login:
post:
tags:
- Users
summary: Log in with email and password
requestBody:
content:
application/json:
schema:
type: object
properties:
email:
type: string
example: 'jdoe@example.com'
password:
type: string
example: 'strong_password123'
responses:
200:
description: |-
User authenticated successfully.
There is no response body. Session will be set via laravel session.
400:
description: |-
Email or password are invalid.
Response string is an enum:
| key | val |
| --- | --- |
| `bad_password` | authentication unsuccessful; this means that there is either no user with this email, or password doesn't match |
422:
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
/api/users/reset:
post:
tags:
- Users
summary: Reset a user's password
description: |-
I know its not secure because anyone can reset anyones password. But here's a counterpoint: its not required to be secure, and i dont care
requestBody:
content:
application/json:
schema:
type: object
properties:
email:
type: string
example: 'jdoe@example.com'
password:
type: string
example: 'very_strong_password123456'
responses:
200:
description: |-
The password is reset
422:
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
/api/users/private/list:
get:
tags:
- Private routes
security:
- session: []
summary: List all users
responses:
200:
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
401:
description: Auth failed
403:
description: Auth failed
post:
tags:
- Private routes
security:
- session: []
summary: List all users with filters
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Filters'
examples:
'Full':
description: |
This demonstrates all possible values of `filters`.
Note that `filters.type` is an enum: `[ "like", "is", "not" ]`, and so is `orders.sort`: `[ "asc", "desc" ]`
value: {
"filters": [
{
"column": "name",
"type": "like",
"filter": "%ad%"
},
{
"column": "name",
"type": "is",
"filter": "jade"
},
{
"column": "name",
"type": "not",
"filter": "jake"
}
],
"orders": [
{
"by": "id",
"sort": "asc"
},
{
"by": "id",
"sort": "desc"
}
],
"pagination": {
"size": 100,
"page": 1
}
}
'Empty':
description: |-
Its important that all keys are passed with empty values. You can't omit a key in this one
value: {
"filters": [],
"orders": [],
"pagination": null
}
'List deleted users':
description: |-
This is the recommended way to list deleted users
value: {
"filters": [
{
"column": "deleted_at",
"type": "not",
"filter": null
}
],
"orders": [],
"pagination": null
}
responses:
200:
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
401:
description: Auth failed
403:
description: Auth failed
/api/users/private/get/{id}:
get:
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Must be a valid UUID
tags:
- Private routes
summary: Get a user
security:
- session: []
responses:
200:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/User'
422:
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
404:
description: User not found
401:
description: Auth failed
403:
description: Auth failed
/api/users/private/edit/{id}:
put:
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Must be a valid UUID
tags:
- Private routes
summary: Edit a user
security:
- session: []
responses:
200:
description: OK
422:
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
401:
description: Auth failed
403:
description: Auth failed
404:
description: User not found
requestBody:
description: |-
All fields are optional. If a field is specified, the database record will change to the field's value.
Note: updating the password will not revoke all current sessions of the user
content:
application/json:
schema:
type: object
properties:
last_name:
type: string
example: doe
name:
type: string
example: jade
middle_name:
type: string
example: john
email:
type: string
example: jdoe@example.com
phone:
type: string
example: '+000000'
password:
type: string
example: 'very_strong_password123456'
/api/users/private/trash/group:
put:
summary: Add user(s) to trash
tags:
- Private routes
security:
- session: []
parameters:
- name: ids
in: query
required: true
schema:
type: string
example: 'comma,separated,values'
description: All must be valid UUIDs
responses:
200:
description: OK
404:
description: One or more users not found
content:
application/json:
schema:
type: array
items:
type: string
example: 'userid'
422:
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
401:
description: Auth failed
403:
description: Auth failed
delete:
summary: Remove user(s) from trash
tags:
- Private routes
security:
- session: []
parameters:
- name: ids
in: query
required: true
schema:
type: string
example: 'comma,separated,values'
description: All must be valid UUIDs
responses:
200:
description: |-
OK
Note: will return OK even if some users were not in trash in the first place
404:
description: One or more users not found
content:
application/json:
schema:
type: array
items:
type: string
example: 'userid'
422:
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
401:
description: Auth failed
403:
description: Auth failed
/api/users/private/trash/clean:
delete:
summary: Delete user(s) for good from trash
tags:
- Private routes
security:
- session: []
parameters:
- name: ids
in: query
required: true
schema:
type: string
example: 'comma,separated,values'
description: All must be valid UUIDs
responses:
200:
description: OK
404:
description: The following user IDs were not in trash in the first place
content:
application/json:
schema:
type: array
items:
type: string
422:
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
401:
description: Auth failed
403:
description: Auth failed
components:
schemas:
User:
type: object
properties:
id:
type: string
example: 'uuid-like'
last_name:
type: string
example: 'doe'
name:
type: string
example: 'john'
middle_name:
type: string
example: 'john'
email:
type: string
example: 'jdoe@example.com'
phone:
type: string
example: '+000000000'
deleted_at:
type: string
example: null
created_at:
type: string
example: null
updated_at:
type: string
example: null
Password:
type: object
properties:
user_id:
type: number
example: 1
password:
type: string
example: 'argon2-hash-here'
ValidationError:
type: object
properties:
field_name:
type: array
items:
type: string
example: 'This field is invalid!'
Filters:
type: object
properties:
filters:
type: array
items:
$ref: '#/components/schemas/Filter'
example: [
{
"column": "name",
"type": "like",
"filter": "%ad%"
},
{
"column": "name",
"type": "is",
"filter": "jade"
},
{
"column": "name",
"type": "not",
"filter": "jake"
}
]
orders:
type: array
items:
$ref: '#/components/schemas/Order'
example: [
{
"by": "id",
"sort": "asc"
},
{
"by": "id",
"sort": "desc"
}
]
pagination:
type: object
properties:
size:
type: number
example: 100
page:
type: number
example: 1
Filter:
type: object
properties:
column:
type: string
example: column_name
type:
type: string
example: 'is'
filter:
type: string
example: '123'
Order:
type: object
properties:
by:
type: string
example: column_name
sort:
type: string
example: 'asc|desc'
securitySchemes:
session:
type: http
scheme: bearer