431 lines
11 KiB
YAML
431 lines
11 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
|
|
/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 of `user` are optional. If a field is specified, the database record will change to the field's value.
|
|
|
|
`password` is optional, only if you want to update the password.
|
|
|
|
Note: updating password will not revoke all current sessions of the user
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
user:
|
|
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
|
|
/api/users/private/trash/list:
|
|
get:
|
|
summary: List users in trash
|
|
tags:
|
|
- Private routes
|
|
security:
|
|
- session: []
|
|
responses:
|
|
200:
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/User'
|
|
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!'
|
|
securitySchemes:
|
|
session:
|
|
type: http
|
|
scheme: bearer
|