megahunt.test/public/openapi.yml

425 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:
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
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
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: []
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
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
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