swagger: add /post/{id} endpoint, fix semantic/grammatical errors

api/swagger.yaml

@@ -12,7 +12,7 @@ paths:
     post:
       tags:
         - Auth Endpoints
-      summary: Attemps to log in a user with credentials, and returns an access token.
+      summary: Attempts to log in a user with credentials, and returns an access token.
       requestBody:
         $ref: '#/components/requestBodies/AuthCredentials'
       responses:
@@ -25,7 +25,7 @@ paths:
         400:
           $ref: '#/components/responses/MalformedBody'
         401:
-          $ref:  '#/components/responses/InvalidCredentials'
+          $ref: '#/components/responses/InvalidCredentials'
         500:
           $ref: '#/components/responses/ServerError'
   /auth/logout:
@@ -34,10 +34,10 @@ paths:
         - Auth Endpoints
       summary: Logs out a user, making their access token invalid.
       security:
-        - token: []
+        - token: [ ]
       responses:
         200:
-          description: You have successfully logged out, and your token is now invalid.
+          description: You have successfully logged out, and the token used to authenticate the request is now revoked/invalid.
           content:
             application/json:
               schema:
@@ -69,8 +69,8 @@ paths:
                 type: object
         400:
           $ref: '#/components/responses/MalformedBody'
-        401:
+        422:
-          $ref: '#/components/responses/InvalidToken'
+          $ref: '#/components/responses/Unprocessable'
         500:
           $ref: '#/components/responses/ServerError'
 
@@ -78,7 +78,7 @@ paths:
     get:
       tags:
         - User Endpoints
-      summary: Get the information for a user.
+      summary: Get information for a user.
       parameters:
         - name: username
           required: true
@@ -108,7 +108,7 @@ paths:
         - $ref: '#/components/parameters/BeforeParam'
         - $ref: '#/components/parameters/LimitParam'
         - $ref: '#/components/parameters/CountParam'
-      summary: Get the list of posts a user has created/submitted.
+      summary: Get a list of posts a user has created/submitted.
       responses:
         200:
           description: A list of posts filtered and formatted.
@@ -140,7 +140,7 @@ paths:
         - $ref: '#/components/parameters/BeforeParam'
         - $ref: '#/components/parameters/LimitParam'
         - $ref: '#/components/parameters/CountParam'
-      summary: Get the list of comments a user has submitted.
+      summary: Get a list of paginated comments a user has submitted.
       responses:
         200:
           description: A list of comments filtered and formatted.
@@ -159,7 +159,9 @@ paths:
 
   /posts:
     get:
-      summary: Get a list of posts
+      tags:
+        - Post Endpoints
+      summary: Get a list of paginated posts
       description: The items retrieved will always show newest first.
       parameters:
         - name: filter
@@ -192,7 +194,7 @@ paths:
       tags:
         - Post Endpoints
       security:
-        - token: []
+        - token: [ ]
       requestBody:
         description: Submit a new post with this endpoint.
         required: true
@@ -228,6 +230,36 @@ paths:
           $ref: '#/components/responses/Unprocessable'
         500:
           $ref: '#/components/responses/ServerError'
+
+  /post/{id}:
+    get:
+      tags:
+        - Post Endpoints
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: The post ID to retrieve information about
+          schema:
+            type: string
+      responses:
+        200:
+          description: Information regarding a post
+          content:
+            application/json:
+              schema:
+                type: object
+                allOf:
+                  - $ref: '#/components/schemas/Post'
+                  - type: object
+                    required:
+                      - comments
+                    properties:
+                      comments:
+                        type: array
+                        items:
+                          $ref: '#/components/schemas/Comment'
+
 components:
   parameters:
     AfterParam:
@@ -249,7 +281,7 @@ components:
     LimitParam:
       name: limit
       in: query
-      description: Maximimum number of items to return
+      description: Maximum number of items to return
       schema:
         type: integer
         maximum: 100
@@ -319,7 +351,7 @@ components:
             reason: Varies
             code: 422
     ServerError:
-      description: The server could not complete a request due to an unknown error. More information may be available in the description.
+      description: The server could not complete a request due to an unknown error. More information may be available in the 'reason' parameter.
       content:
         application/json:
           schema:
@@ -336,13 +368,13 @@ components:
         - password
       properties:
         username:
-          description: A Unique uusername to identify a user around the website.
+          description: A unique username to identify a user around the website.
           type: string
           minLength: 3
           maxLength: 16
           pattern: "[a-zA-Z0-9 ]{3,16}"
         email:
-          description: A Unique email used for communication/further identification.
+          description: A unique email used for communication/further identification.
           type: string
           format: email
         password:
@@ -357,6 +389,20 @@ components:
         - username
         - points
         - date_created
+      properties:
+        id:
+          type: string
+          description: The unique ID of the user
+        username:
+          type: string
+          description: The username of the user
+        points:
+          type: number
+          description: The number of points (sum of upvotes and downvotes) of a user
+        date_created:
+          type: string
+          format: 'date-time'
+          description: When the user's account was created
     Token:
       required:
         - token
@@ -448,4 +494,4 @@ components:
   securitySchemes:
     token:
       type: http
-      scheme: bearer
+      scheme: bearer