Merge pull request #24 from hogum/ch-document-163175325

#163175325 Create the Application Documentation

app/__init__.py

@@ -1,4 +1,6 @@
 from flask import Flask
+from flask_cors import CORS
+from flasgger import Swagger
 
 from app.api.v1 import auth_blueprint, app_blueprint
 from instance.config import APP_CONFIG
@@ -12,4 +14,21 @@ def create_app(config_setting):
     app.config.from_object(
         APP_CONFIG[config_setting.strip().lower()])
 
+    CORS(app)
+
+    description = "Questioner is an API application allowing a user to\
+                    register, login, ask questions to meetups and\
+                    vote on questions posted to present meetups."
+
+    template = {
+        "swagger": "3.0",
+        "info": {
+            "title": "Questioner API",
+            "description": description,
+            "version": "1.0"
+        }
+    }
+
+    Swagger(app, template=template)
+
     return app

app/api/v1/utils/helpers.py

@@ -2,9 +2,9 @@
     This module contains validators for user data passed in request
     arguments.
 """
-from flask import request
+
 import re
-from functools import wraps
+import datetime
 
 name_pattern = re.compile(r'^[A-Za-z]+$')
 
@@ -23,3 +23,15 @@ def verify_name(value, item):
         raise ValueError(f'Oops! {value} has NUMBERS.' +
                          f' {item} should contain letters only')
     return value
+
+
+def validate_date(value):
+    """
+        Ensures passing of valid datetime format in date inputs
+    """
+    try:
+        datetime.datetime.strptime(value, '%Y-%m-%dT%H:%M:%S')
+    except ValueError:
+        raise ValueError(
+            "Incorrect data format, should be YYYY-MM-DDTHH:MM:SS")
+    return value

app/api/v1/views/docs/auth_get_users.yml

@@ -0,0 +1,22 @@
+Get Registered Users
+
+This endpoint allows a registered Admin user to see all registered users.
+
+---
+tags:
+- Authorization
+parameters:
+- in: header
+  name: Authorization
+  description: The authorization token generated during user
+    login (Bearer + token)
+  type: string
+  required: true
+
+responses:
+  200:
+    description: Success
+  400:
+    description: Bad Request, validation check failed.
+  403:
+    description: Anauthorized request. The user does not have the priviledges to perform that request

app/api/v1/views/docs/auth_logout.yml

@@ -0,0 +1,24 @@
+Log out User
+
+This endpoint allows a logged in user to log out of the application.
+Both the Administrator and a non-admin user can use this endpoint.
+This endpoint adds the access token of the user to the blacklist so that it cannot be used
+to access protected endpoints.
+---
+tags:
+- Authorization
+parameters:
+- in: header
+  name: Authorization
+  description: The authorization token generated during user
+    login (Bearer + token)
+  type: string
+  required: true
+responses:
+  200:
+    description: Success, logout successful, token has been revoked
+  400:
+    description: Bad Request, validation check failed.
+
+  403:
+    description: Anauthorized. Logout attempt for a missing session

app/api/v1/views/docs/auth_register.yml

@@ -0,0 +1,48 @@
+Register User
+This endpoint allows a user to register.
+example Registration role is non-admin.
+---
+tags:
+- Authorization
+consumes:
+- application/json
+parameters:
+- in: body
+  name: Registration Details
+  description: The details of the user to be registered
+  schema:
+    type: object
+    required:
+    - username
+    - email
+    - password
+
+    properties:
+      username:
+        type: string
+        example: DomesticCow
+      email:
+        type: string
+        example: domestic@mammals.milk
+      password:
+        type: string
+        example: pa55word
+      firstname:
+        type: string
+        example: Domestic
+      lastname:
+        type: string
+        example: Cow
+      isAdmin:
+        type: boolean
+        example: true
+      phonenumber:
+        type: integer
+        example: 01234567
+responses:
+  201:
+    description: Success, the user has been created
+  400:
+    description: Bad Request, validation check failed.
+  409:
+    description: User exists

app/api/v1/views/docs/login.yml

@@ -0,0 +1,38 @@
+Login User
+This endpoint allows a registered user to login.
+Both an Administrator and a non-admin user can use this endpoint
+to access protected resources.
+---
+tags:
+- Authorization
+consumes:
+- application/json
+parameters:
+- in: body
+  name: Login Credentials
+  description: The User credentials for login
+  schema:
+    type: object
+    required:
+    - email
+    - password
+    properties:
+      email:
+        type: string
+        example: domestic@mammals.milk
+      username:
+        type: string
+        example: DomesticCow
+      password:
+        type: string
+        example: pa55word
+
+responses:
+  200:
+    description: Success, login successful, access token is generated and returned in response body
+  400:
+    description: Bad Request, validation check failed.
+  404:
+    description: Not found, user with provided is not registered
+  403:
+    description: Wrong Password

app/api/v1/views/docs/meetup_delete.yml

@@ -0,0 +1,27 @@
+Delete a Meetup
+Allows the removal of a produt from the inventory
+This endpoint is only accessible to the Admin
+---
+tags:
+- Meetups
+parameters:
+- in: header
+  name: Authorization
+  description: The encoded token generated during user login
+    example (Bearer token)
+  type: string
+  required: true
+- in: path
+  name: Meetup_id
+  type: integer
+  required: true
+  description: The id of the Meetup to delete.
+responses:
+  200:
+    description: Success, Meetup Deleted
+  400:
+    description: Bad Request. Validation failed
+  403:
+    description: Unauthorized, response when Attendant tries to delete a Meetup
+  404:
+    description: Returned when Meetup with id specified does not exist.

app/api/v1/views/docs/meetup_get.yml

@@ -0,0 +1,29 @@
+Get a Single meetup
+Returns a meetup posted to a meetup with the specified id.
+---
+tags:
+- Meetups
+parameters:
+- in: header
+  name: Authorization
+  description: The encoded token generated during
+    user login i.e (Bearer token)
+  type: string
+  required: true
+- in: path
+  name: id   # Note the name is the same as in the path
+  required: true
+  schema:
+    type: integer
+    minimum: 1
+    description: The id of the meetup records to retrieve
+responses:
+  200:
+    description: Success. meetup with specified id is
+      returned successfully
+  404:
+    description: Not Fouund, no meetup id matches the id given
+  403:
+    description: Anauthorized request
+  400:
+    description: Bad Request. Invalid Authorization header or illegal token

app/api/v1/views/docs/meetup_post.yml

@@ -0,0 +1,54 @@
+Add New Meetup
+This endpoint allows the addition of a new Meetup to the inventory.
+Only Administrator can add a Meetup.
+---
+tags:
+- Meetups
+consumes:
+- application/json
+parameters:
+- in: header
+  name: Authorization
+  description: The encoded token generated during user
+    login example (Bearer token)
+  type: string
+  required: true
+- in: body
+  name: Meetup Details
+  description: The Details of the Meetup to be added to Inventory
+  schema:
+    type: object
+    required:
+    - topic
+    - location
+    properties:
+      topic:
+        type: string
+        example: The ways of making Mammals happy
+      location:
+        type: string
+        example: pkoroco Ranch, Nyeri, Kenya
+      happeningOn:
+        type: string
+        example: '2019-08-04T12:00:00'
+        format: date
+      images:
+        type: array
+        items:
+          type: string
+        example: [file_path, file_path]
+      tags:
+        type: array
+        items:
+          type: string
+        example: [milking, domestic, mammals]
+
+responses:
+  201:
+    description: Success, the Meetup has been added successfully
+  403:
+    description: Unauthorized. A non-admin user trying to create a meetup
+  400:
+    description: Bad Request, handles failed validation.
+  409:
+    description: Attempt to recreate exisring meetup

app/api/v1/views/docs/meetups_get.yml

@@ -0,0 +1,18 @@
+Retrieve All Meetups
+Returns all the Meetups created by the Administrator
+---
+tags:
+- Meetups
+parameters:
+- in: header
+  name: Authorization
+  description: The encoded token generated during user
+    login i.e (Bearer token)
+  type: string
+  required: true
+responses:
+  200:
+    description: Success, Meetups retrieved.
+
+  403:
+    description: Authorization Access. User not signed in.

app/api/v1/views/docs/question_delete.yml

@@ -0,0 +1,29 @@
+Delete a Question
+Returns a question posted to a meetup with the specified id.
+---
+tags:
+- Meetup Questions
+parameters:
+- in: header
+  name: Authorization
+  description: The encoded token generated during
+    user login i.e (Bearer token)
+  type: string
+  required: true
+- in: path
+  name: id   # Note the name is the same as in the path
+  required: true
+  schema:
+    type: integer
+    minimum: 1
+    description: The id of the question records to retrieve
+responses:
+  200:
+    description: Success. Question with specified id is
+      deleted successfully
+  404:
+    description: Not Found, no question id matches the id given
+  403:
+    description: Anauthorized request
+  400:
+    description: Bad Request. Invalid Authorization header or illegal token

app/api/v1/views/docs/question_get.yml

@@ -0,0 +1,29 @@
+Get a Single Question
+Returns a question posted to a meetup with the specified id.
+---
+tags:
+- Meetup Questions
+parameters:
+- in: header
+  name: Authorization
+  description: The encoded token generated during
+    user login i.e (Bearer token)
+  type: string
+  required: true
+- in: path
+  name: id   # Note the name is the same as in the path
+  required: true
+  schema:
+    type: integer
+    minimum: 1
+    description: The id of the question records to retrieve
+responses:
+  200:
+    description: Success. Question with specified id is
+      returned successfully
+  404:
+    description: Not Fouund, no question id matches the id given
+  403:
+    description: Anauthorized request
+  400:
+    description: Bad Request. Invalid Authorization header or illegal token