megahunt.test/public/openapi.yml

326 lines
8.4 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:
user:
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'
/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_email` | email is not a valid email |
| `bad_password` | authentication unsuccessful; this means that there is either no user with this email, or password doesn't match |
This error also might be sent by laravel if your body is corrupted
/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'
new_pass:
type: string
example: 'very_strong_password123456'
responses:
200:
description: |-
The password is reset
/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'
/api/users/private/get/{id}:
get:
parameters:
- name: id
in: path
required: true
schema:
type: string
tags:
- Private routes
security:
- session: []
responses:
200:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/User'
400:
description: Invalid ID
404:
description: User not found
/api/users/private/edit/{id}:
put:
parameters:
- name: id
in: path
required: true
schema:
type: string
tags:
- Private routes
security:
- session: []
responses:
200:
description: OK
requestBody:
description: |-
All fields of `user` are required. The whole record will be updated with exactly what you provide here. It is assumed that you already have all information about the user beforehand
`new_pass` is optional, only if you want to update the password.
Note: updating password will revoke all current sessions of the user
content:
application/json:
schema:
type: object
properties:
user:
$ref: '#/components/schemas/User'
new_pass:
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'
responses:
200:
description: OK
404:
description: One or more users not found
content:
application/json:
schema:
type: array
items:
type: string
example: 'userid'
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'
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'
/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'
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
/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'
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'
securitySchemes:
session:
type: http
scheme: bearer