swagger: add security scheme, improve api semantics

api/swagger.yaml

@@ -33,8 +33,8 @@ paths:
       tags:
         - Auth Endpoints
       summary: Logs out a user, making their access token invalid.
-      requestBody:
+      security:
-        $ref: '#/components/requestBodies/TokenRequest'
+        - token: []
       responses:
         200:
           description: You have successfully logged out, and your token is now invalid.
@@ -75,7 +75,7 @@ paths:
           $ref: '#/components/responses/ServerError'
 
   /users/{username}:
-    post:
+    get:
       tags:
         - User Endpoints
       summary: Get the information for a user.
@@ -94,7 +94,7 @@ paths:
                 $ref: '#/components/schemas/User'
 
   /users/{username}/posts:
-    post:
+    get:
       tags:
         - User Endpoints
         - Post Endpoints
@@ -104,9 +104,11 @@ paths:
           in: path
           schema:
             type: string
+        - $ref: '#/components/parameters/AfterParam'
+        - $ref: '#/components/parameters/BeforeParam'
+        - $ref: '#/components/parameters/LimitParam'
+        - $ref: '#/components/parameters/CountParam'
       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.
@@ -124,7 +126,7 @@ paths:
           $ref: '#/components/responses/ServerError'
 
   /users/{username}/comments:
-    post:
+    get:
       tags:
         - User Endpoints
         - Comments Endpoints
@@ -134,9 +136,11 @@ paths:
           in: path
           schema:
             type: string
+        - $ref: '#/components/parameters/AfterParam'
+        - $ref: '#/components/parameters/BeforeParam'
+        - $ref: '#/components/parameters/LimitParam'
+        - $ref: '#/components/parameters/CountParam'
       summary: Get the list of comments a user has submitted.
-      requestBody:
-        $ref: '#/components/requestBodies/Listing'
       responses:
         200:
           description: A list of comments filtered and formatted.
@@ -157,6 +161,8 @@ paths:
     post:
       tags:
         - Post Endpoints
+      security:
+        - token: []
       requestBody:
         description: Submit a new post with this endpoint.
         required: true
@@ -164,18 +170,14 @@ paths:
           application/json:
             schema:
               required:
-                - token
                 - title
               properties:
-                token:
-                  description: The access token.
                 title:
                   description: The title of the post created
                   type: string
                 description:
                   description: The body text of a post, optional.
             example:
-              token: abcdef12345678901234
               title: I use arch BTW.
               description: Ladies, I'm waiting.
       responses:
@@ -196,8 +198,41 @@ paths:
           $ref: '#/components/responses/Unprocessable'
         500:
           $ref: '#/components/responses/ServerError'
-
 components:
+  parameters:
+    AfterParam:
+      name: after
+      in: query
+      description: Date after which to return items.
+      schema:
+        type: string
+        format: 'date-time'
+        example: 2020-01-01T00:00:00.000z
+    BeforeParam:
+      name: before
+      in: query
+      description: Date before which to return items.
+      schema:
+        type: string
+        format: 'date-time'
+        example: 2030-01-01T00:00:00.000z
+    LimitParam:
+      name: limit
+      in: query
+      description: Maximimum number of items to return
+      schema:
+        type: integer
+        maximum: 100
+        minimum: 0
+    CountParam:
+      name: count
+      in: query
+      description: The number of items already seen in this listing. Items will always be sorted by newest first.
+      schema:
+        type: integer
+        default: 0
+        minimum: 0
+
   requestBodies:
     AuthCredentials:
       description: User credentials.
@@ -216,24 +251,6 @@ components:
               password:
                 description: The password of the user.
                 type: string
-    TokenRequest:
-      description: The access token to identify a user.
-      required: true
-      content:
-        application/json:
-          schema:
-            required:
-              - token
-            properties:
-              token:
-                description: The access token.
-                type: string
-    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.
@@ -398,32 +415,7 @@ components:
         code:
           description: The HTTP error code value accompanying the error.
           type: integer
-    Listing:
+  securitySchemes:
-      type: object
+    token:
-      properties:
+      type: http
-        after:
+      scheme: bearer
-          description: Filter items to only return those after this date and time.
-          type: string
-          format: 'date-time'
-          default: 2020-01-01T00:00:00.000z
-        before:
-          description: Filter items to only return those before this date and time.
-          type: string
-          format: 'date-time'
-          default: 2030-01-01T00:00:00.000z
-        count:
-          description: The number of items already seen in this listing. Items will always be sorted by newest first.
-          type: integer
-          minimum: 0
-          default: 0
-        limit:
-          description: The maximum number of items to provide. Can be used in conjunction with 'count' to paginate.
-          type: integer
-          maximum: 100
-          minimum: 0
-          default: 10
-      example:
-        after: 2020-01-01T00:00:00.000z
-        before: 2030-01-01T00:00:00.000z
-        count: 0
-        limit: 10