From 8302b02b908a3e5249782b39f05d0f7d823c8e5d Mon Sep 17 00:00:00 2001
From: Hamza Ali <me@hamzantal.pw>
Date: Wed, 9 Sep 2020 22:43:10 +0700
Subject: [PATCH] swagger: add user endpoint to get user info, and their posts

---
 api/swagger.yaml | 101 ++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 100 insertions(+), 1 deletion(-)

diff --git a/api/swagger.yaml b/api/swagger.yaml
index b3c02e8..5a91358 100644
--- a/api/swagger.yaml
+++ b/api/swagger.yaml
@@ -74,6 +74,47 @@ paths:
         500:
           $ref: '#/components/responses/ServerError'
 
+  /users/{username}:
+    get:
+      tags:
+        - User Endpoints
+      summary: Get the information for a user
+      parameters:
+        - name: username
+          required: true
+          in: path
+          schema:
+            type: string
+      responses:
+        200:
+          description: Public information for the requested user.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+
+  /users/{username}/posts:
+    get:
+      tags:
+        - User Endpoints
+        - Posts Endpoints
+      summary: Get the list of posts a user has created/submitted.
+      requestBody:
+        $ref: '#/components/requestBodies/Listing'
+      responses:
+        200:
+          description: A list of posts filtered and formatted.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Post'
+        400:
+          $ref: '#/components/responses/MalformedBody'
+        422:
+          $ref: '#/components/responses/Unprocessable'
+        500:
+          $ref: '#/components/responses/ServerError'
+
 components:
   requestBodies:
     AuthCredentials:
@@ -104,6 +145,12 @@ components:
               token:
                 type: string
                 description: The access token.
+    Listing:
+      description: Query particular data sorted by date and time.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Listing'
   responses:
     MalformedBody:
       description: The information in your body is incomplete, or your JSON format is invalid.
@@ -132,6 +179,15 @@ components:
           example:
             reason: The token provided is invalid.
             code: 401
+    Unprocessable:
+      description: The request was valid, however some of the parameters have an invalid value.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            reason: Varies
+            code: 422
     ServerError:
       description: The server could not complete a request due to an unknown error. More informatino may be available in the description.
       content:
@@ -164,6 +220,13 @@ components:
           format: password
           minLength: 8
           maxLength: 32
+    User:
+      type: object
+      required:
+        - id
+        - username
+        - points
+        - date_created
     Token:
       required:
         - token
@@ -172,6 +235,15 @@ components:
         token:
           type: string
           description: The access token value
+    Post:
+      type: object
+      required:
+        - id
+        - user_id
+        - title
+        - description
+        - upvotes
+        - downvotes
     Error:
       required:
         - reason
@@ -183,4 +255,31 @@ components:
           description: The cause of the error message
         code:
           type: integer
-          description: The HTTP error code value accompanying the error.
\ No newline at end of file
+          description: The HTTP error code value accompanying the error.
+    Listing:
+      type: object
+      properties:
+        after:
+          type: string
+          format: 'date-time'
+          description: Filter items to only return those after this date and time.
+          default: 2020-01-01T00:00:00.000z
+        before:
+          type: string
+          format: 'date-time'
+          description: Filter items to only return those before this date and time.
+          default: 2030-01-01T00:00:00.000z
+        count:
+          type: integer
+          description: The number of items already seen in this listing. Items will always be sorted by newest first.
+          default: 0
+        limit:
+          type: integer
+          maximum: 100
+          description: The maximum number of items to provide. Can be used in conjunction with 'count' to paginate.
+          default: 10
+      example:
+        after: 2020-01-01T00:00:00.000z
+        before: 2030-01-01T00:00:00.000z
+        count: 0
+        limit: 10
\ No newline at end of file