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 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 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