feat: openapi

public/openapi.yml

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