559 lines
15 KiB
YAML
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
|