swagger: add new post endpoint.

api/swagger.yaml

@@ -75,10 +75,10 @@ paths:
           $ref: '#/components/responses/ServerError'
 
   /users/{username}:
-    get:
+    post:
       tags:
         - User Endpoints
-      summary: Get the information for a user
+      summary: Get the information for a user.
       parameters:
         - name: username
           required: true
@@ -97,7 +97,7 @@ paths:
     post:
       tags:
         - User Endpoints
-        - Posts Endpoints
+        - Post Endpoints
       parameters:
         - name: username
           required: true
@@ -153,6 +153,50 @@ paths:
         500:
           $ref: '#/components/responses/ServerError'
 
+  /posts/new:
+    post:
+      tags:
+        - Post Endpoints
+      requestBody:
+        description: Submit a new post with this endpoint.
+        required: true
+        content:
+          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:
+        200:
+          description: The created post ID
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id:
+                    type: string
+        400:
+          $ref: '#/components/responses/MalformedBody'
+        401:
+          $ref: '#/components/responses/InvalidToken'
+        422:
+          $ref: '#/components/responses/Unprocessable'
+        500:
+          $ref: '#/components/responses/ServerError'
+
 components:
   requestBodies:
     AuthCredentials:
@@ -174,6 +218,7 @@ components:
                 type: string
     TokenRequest:
       description: The access token to identify a user.
+      required: true
       content:
         application/json:
           schema:
@@ -348,7 +393,7 @@ components:
       type: object
       properties:
         reason:
-          description: The cause of the error message
+          description: The cause of the error message.
           type: string
         code:
           description: The HTTP error code value accompanying the error.