swagger: add login endpoint + base details

api/swagger.yaml

@@ -0,0 +1,99 @@
+openapi: 3.0.3
+info:
+  title: Project Ham API Specification
+  version: 0.0.1
+  contact:
+    name: Project Maintainer
+    email: me@hamzantal.pw
+  license:
+    name: MIT
+paths:
+  /auth/login:
+    post:
+      tags:
+        - Auth Endpoints
+      summary: Attemps to log in a user with credentials, and returns an access token.
+      requestBody:
+        $ref: '#/components/requestBodies/AuthCredentials'
+      responses:
+        200:
+          description: You have been successfully logged in, and you can use the token to interact with the web server.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Token'
+        400:
+          $ref: '#/components/responses/MalformedBody'
+        401:
+          $ref:  '#/components/responses/InvalidCredentials'
+        500:
+          $ref: '#/components/responses/ServerError'
+
+components:
+  requestBodies:
+    AuthCredentials:
+      description: User credentials.
+      required: true
+      content:
+        application/json:
+          schema:
+            required:
+              - username
+              - password
+            type: object
+            properties:
+              username:
+                type: string
+                description: The username of the user.
+              password:
+                type: string
+                description: The password of the user.
+  responses:
+    MalformedBody:
+      description: The information in your body is incomplete, or your JSON format is invalid.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            reason: Invalid request body provided.
+            code: 400
+    InvalidCredentials:
+      description: The credentials you have provided are incorrect.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            reason: The username or password provided are incorrect.
+            code: 401
+    ServerError:
+      description: The server could not complete a request due to an unknown error. More informatino may be available in the description.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            reason: The internal server reached an unknown state.
+            code: 500
+  schemas:
+    Token:
+      required:
+        - token
+      type: object
+      properties:
+        token:
+          type: string
+          description: The access token value
+    Error:
+      required:
+        - reason
+        - code
+      type: object
+      properties:
+        reason:
+          type: string
+          description: The cause of the error message
+        code:
+          type: integer
+          description: The HTTP error code value accompanying the error.