bug(improve api doc): make api documentation more readable and intera…

…ctive

[Finishes #167942825]

src/config/swagger.js

@@ -7,7 +7,7 @@ const swaggerDefinition = {
   info: {
     title: 'Authors Haven',
     version: '1.0.0',
-    description: 'A Social platform for the creative at heart'
+    description: 'A Social platform for the creative at heart. Create a community of like minded authors to foster inspiration and innovation by leveraging the modern web.'
   },
   host: `${process.env.BASE_URL}:${process.env.PORT}/api/`,
   basePath: `${process.env.API_VERSION}`,
@@ -16,7 +16,7 @@ const swaggerDefinition = {
 
 const options = {
   swaggerDefinition,
-  apis: ['./src/routes/**/*.js']
+  apis: ['./src/routes/**/*.yml']
 };
 
 const swaggerSpecification = swaggerJSDoc(options);

src/routes/api/article/doc.yml

@@ -0,0 +1,212 @@
+/articles/{slug}:
+  get:
+    summary: Gets a a particular article
+    description: >
+      Get a information about a specific article
+    tags:
+      - Article
+    produces:
+      - application/json
+    parameters:
+      - name: x-access-token
+        in: header
+        schema:
+          type: string
+        required:
+          - authorization
+      - name: slug
+        in: path
+        description: Slug for article 
+        type: string
+        required: true
+    responses:
+      200:
+        description: OK
+        schema:
+          $ref: '#definitions/Article'
+  patch:
+    summary: Updates an article
+    description: >
+      updates a specific article
+    tags:
+      - Article
+    produces:
+      - application/json
+    parameters:
+      - name: x-access-token
+        in: header
+        schema:
+          type: string
+        required:
+          - authorization
+      - name: articleSlug
+        in: path
+        description: Slug for article being updated
+        type: string
+        required: true
+      - name: article
+        in: body
+        description: article new data
+        schema:
+          $ref: '#definitions/Article'
+    responses:
+      200:
+        description: Article successfully updated
+        schema:
+          $ref: '#definitions/Article'
+      400:
+        $ref: '#responses/BadRequest'
+  delete:
+    summary: delete a specific article
+    tags:
+      - Article
+    description: >
+      deletes a particular article
+    produces:
+      - application/json
+    parameters:
+      - name: x-access-token
+        in: header
+        schema:
+          type: string
+        required:
+          - authorization
+      - name: slug
+        in: path
+        description: Slug for article being deleted
+        type: string
+        required: true
+    responses:
+      200:
+        description: Article successfully deleted
+        schema:
+          $ref: '#definitions/Article'
+      400:
+        $ref: '#/responses/BadRequest'
+      404:
+        $ref: '#/responses/Notfound' 
+/articles:
+  post:
+    summary: Create an article
+    description: >
+      Creates a specific article
+    tags:
+      - Article
+    produces:
+      - application/json
+    parameters:
+      - name: x-access-token
+        in: header
+        schema:
+          type: string
+        required:
+          - authorization
+      - name: Article
+        in: body
+        description: article rating
+        schema:
+          $ref: '#definitions/Article'
+    responses:
+      200:
+        description: Article successfully created
+        schema:
+          $ref: '#definitions/Article'
+      400:
+        $ref: '#responses/BadRequest'
+      404:
+        $ref: '#/responses/Notfound'
+    get:
+      summary: Gets all articles
+      description: >
+        Get a information about a all articles
+      tags:
+        - Article
+      produces:
+        - application/json
+      parameters:
+        - name: x-access-token
+          in: header
+          schema:
+            type: string
+          required:
+            - authorization
+      responses:
+        200:
+          description: OK
+          schema:
+            $ref: '#definitions/Article'
+        404:
+          $ref: '#/responses/Notfound'
+tags:
+- name: Article
+  description: Operations related to Article
+responses:
+  success:
+    description: Success
+    schema:
+      $ref: '#/definitions/Article'
+  BadRequest:
+    description: Bad request
+    schema:
+      $ref: '#/definitions/Error'
+  Notfound:
+    description: Not found
+    schema:
+      $ref: '#/definitions/Error'
+definitions:
+  Article:
+    type: object
+    properties:
+      slug:
+        type: string
+        description: article slug
+      title:
+        type: string
+        description: article title
+      description:
+        type: string
+        description: article description
+      body:
+        type: string
+        description: article body
+      taglist:
+        type: array
+        items:
+          type: string
+        description: article tags
+      favorited:
+        type: boolean
+        description: is article favorited
+      favoritesCount:
+        type: integer
+        description: article tags
+      author:
+        type: object
+        properties:
+          username:
+            type: string
+          bio:
+            type: string
+          image:
+            type: string
+          following:
+            type: boolean
+        description: Article's author details
+    required:
+      - slug
+      - title
+      - description
+      - body
+      - tagList
+      - favorited
+      - favoritesCount
+      - author
+  Error:
+    type: object
+    properties:
+      status:
+        type: string
+        description: status code
+      message:
+        type: string
+        description: description of error

src/routes/api/comment/doc.yml

@@ -0,0 +1,153 @@
+
+/comments/{slug}:
+  post:
+    summary: creates a comment on an article
+    description: >
+      creates a comment on an article
+    tags:
+      - Comment
+    produces:
+      - application/json
+    parameters:
+      - name: x-access-token
+        in: header
+        schema:
+          type: string
+        required:
+          - authorization
+      - name: slug
+        in: path
+        description: Slug for article 
+        type: string
+        required: true
+      - name: body
+        in: body
+        description: comment data
+        schema:
+          $ref: '#definitions/Comment'
+    responses:
+      200:
+        description: OK
+        schema:
+          $ref: '#definitions/Comment'
+/comments/{id}:
+  put:
+    summary: Updates a comment
+    description: >
+      updates a specific comment
+    tags:
+      - Comment
+    produces:
+      - application/json
+    parameters:
+      - name: x-access-token
+        in: header
+        schema:
+          type: string
+        required:
+          - authorization
+      - name: id
+        in: path
+        description: id for article 
+        type: string
+        required: true
+      - name: body
+        in: body
+        description: comment new data
+        schema:
+          $ref: '#definitions/Comment'
+    responses:
+      200:
+        description: Comment successfully updated
+        schema:
+          $ref: '#definitions/Comment'
+      400:
+        $ref: '#responses/BadRequest'
+  delete:
+    summary: delete a specific comment
+    tags:
+      - Comment
+    description: >
+      deletes a particular comment
+    produces:
+      - application/json
+    parameters:
+      - name: x-access-token
+        in: header
+        schema:
+          type: string
+        required:
+          - authorization
+      - name: id
+        in: path
+        description: id for comment being deleted
+        type: string
+        required: true
+    responses:
+      200:
+        description: Comment successfully deleted
+        schema:
+          $ref: '#definitions/Comment'
+      400:
+        $ref: '#/responses/BadRequest'
+      404:
+        $ref: '#/responses/Notfound' 
+/comments:
+  get:
+    summary: get a comment
+    description: >
+      gets a specific comment
+    tags:
+      - Comment
+    produces:
+      - application/json
+    parameters:
+      - name: x-access-token
+        in: header
+        schema:
+          type: string
+        required:
+          - authorization
+    responses:
+      200:
+        description: Successfully retrieved comment
+        schema:
+          $ref: '#definitions/Comment'
+      400:
+        $ref: '#responses/BadRequest'
+      404:
+        $ref: '#/responses/Notfound'
+tags:
+- name: Comment
+  description: Operations related to Comment
+responses:
+  success:
+    description: Success
+    schema:
+      $ref: '#/definitions/Comment'
+  BadRequest:
+    description: Bad request
+    schema:
+      $ref: '#/definitions/Error'
+  Notfound:
+    description: Not found
+    schema:
+      $ref: '#/definitions/Error'
+definitions:
+  Comment:
+    type: object
+    properties:
+      body:
+        type: string
+        description: comment body
+      required:
+      - body
+  Error:
+    type: object
+    properties:
+      status:
+        type: string
+        description: status code
+      message:
+        type: string
+        description: description of error