swagger: add logout endpoint

api/swagger.yaml

@@ -28,6 +28,26 @@ paths:
           $ref:  '#/components/responses/InvalidCredentials'
         500:
           $ref: '#/components/responses/ServerError'
+  /auth/logout:
+    post:
+      tags:
+        - Auth Endpoints
+      summary: Logs out a user, making their access token invalid.
+      requestBody:
+        $ref: '#/components/requestBodies/TokenRequest'
+      responses:
+        200:
+          description: You have successfully logged out, and your token is now invalid.
+          content:
+            application/json:
+              schema:
+                type: object
+        400:
+          $ref: '#/components/responses/MalformedBody'
+        401:
+          $ref: '#/components/responses/InvalidToken'
+        500:
+          $ref: '#/components/responses/ServerError'
 
 components:
   requestBodies:
@@ -48,6 +68,17 @@ components:
               password:
                 type: string
                 description: The password of the user.
+    TokenRequest:
+      description: The access token to identify a user.
+      content:
+        application/json:
+          schema:
+            required:
+              - token
+            properties:
+              token:
+                type: string
+                description: The access token.
   responses:
     MalformedBody:
       description: The information in your body is incomplete, or your JSON format is invalid.
@@ -67,6 +98,15 @@ components:
           example:
             reason: The username or password provided are incorrect.
             code: 401
+    InvalidToken:
+      description: The access token you provided is invalid or missing.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            reason: The token provided is invalid.
+            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: