feat: openapi
This commit is contained in:
parent
1b0af8bebf
commit
e78fb556a3
GPG Key ID:
14546221E3595D0C
|
|
@ -0,0 +1,318 @@
|
|||
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/reg:
|
||||
put:
|
||||
description: Create new user
|
||||
tags:
|
||||
- Users
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
user:
|
||||
$ref: '#/components/schemas/User'
|
||||
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 |
|
||||
| --- | --- |
|
||||
| `bad_password` | the password is too weak. it must score at least 3 by zxcvbn |
|
||||
| `bad_email` | email doesn't match the email regex |
|
||||
| `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
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
email:
|
||||
type: string
|
||||
example: 'jdoe@example.com'
|
||||
responses:
|
||||
200:
|
||||
description: |-
|
||||
A reset password link is sent to the email, if such an account exists.
|
||||
|
||||
If no mailer is set and it is debug mode, link will be available in `X-Reset-Link`
|
||||
400:
|
||||
description: |-
|
||||
Invalid email
|
||||
|
||||
This error also might be sent by laravel if your body is corrupted
|
||||
|
||||
/api/users/private/list:
|
||||
get:
|
||||
tags:
|
||||
- Private routes
|
||||
security:
|
||||
- jwt: []
|
||||
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:
|
||||
- jwt: []
|
||||
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:
|
||||
- jwt: []
|
||||
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:
|
||||
- jwt: []
|
||||
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:
|
||||
- jwt: []
|
||||
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:
|
||||
- jwt: []
|
||||
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:
|
||||
- jwt: []
|
||||
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:
|
||||
jwt:
|
||||
type: http
|
||||
scheme: bearer
|
||||
File diff suppressed because one or more lines are too long
Loading…
Reference in New Issue