Feat/swagger spec

api/controllers/bid_controller.py

@@ -1,12 +1,12 @@
 
 from flask import Blueprint
-from api.models.bid_models import get_test, create_bid
+from api.models.bid_models import get_bids, create_bid
 
 bid = Blueprint('bid', __name__)
 
 @bid.route("/bids", methods=["GET"])
-def get_tested():
-    response = get_test()
+def get_all_bids():
+    response = get_bids()
     return response
 
 @bid.route("/bids", methods=["POST"])

api/models/bid_models.py

@@ -1,8 +1,12 @@
 from flask import request, jsonify
 from api.schemas.bid_schema import BidSchema, Status
 
-def get_test():
-    return 'test', 200
+def get_bids():
+    f = open('./db.txt','r')
+    bids = f.read()
+    f.close()
+    return bids, 200
+
 
 def create_bid():
     mandatory_fields = ['tender', 'client', 'bid_date']
@@ -28,7 +32,7 @@ def create_bid():
     # Set failed phase info
     # bid_schema.setFailedPhase(phase=3, has_score=True, score=50, out_of=100)
     # Change status
-    # bid_schema.setStatus('deleted')
+    bid_schema.setStatus(Status.DELETED)
     # Convert the mock BidSchema object to a dictionary
     bid_json = bid_schema.toDbCollection()
 

api/schemas/bid_schema.py

@@ -33,8 +33,8 @@ def setFailedPhase(self, phase, has_score, score=None, out_of=None):
          self.failed = PhaseInfo(phase=phase, has_score=has_score, score=score, out_of=out_of)
 
     def setStatus(self, status):
-        if hasattr(Status, status):
-            self.status = status
+        if isinstance(status, Status):
+            self.status = status.name.lower()
         else:
             raise ValueError("Invalid status. Please provide a valid Status enum value")
 

api/schemas/phase_schema.py

@@ -1,6 +1,6 @@
 # Schema for phaseInfo object
 class PhaseInfo:
-    def __init__(self, phase, has_score, score=None, out_of=None):
+    def __init__(self, phase, has_score, score=int, out_of=int):
             self.phase = phase
             self.has_score = has_score
             self.score = score

api/schemas/status_schema.py

@@ -2,6 +2,6 @@
 
 # Enum for status
 class Status(Enum):
-    deleted = 1
-    in_progress = 2
-    completed = 3
+    DELETED = 1
+    IN_PROGRESS = 2
+    COMPLETED = 3

app.py

@@ -1,9 +1,22 @@
 from flask import Flask
+from flask_swagger_ui import get_swaggerui_blueprint
 
 from api.controllers.bid_controller import bid
 
 app = Flask(__name__)
 
+SWAGGER_URL = '/api/docs'  # URL for exposing Swagger UI (without trailing '/')
+API_URL = '/static/swagger_config.yml'  # Our API url (can of course be a local resource)
+
+# Call factory function to create our blueprint
+swaggerui_blueprint = get_swaggerui_blueprint(
+    SWAGGER_URL,  # Swagger UI static files will be mapped to '{SWAGGER_URL}/dist/'
+    API_URL,
+    config={  # Swagger UI config overrides
+        'app_name': "Test application"
+    })
+
+app.register_blueprint(swaggerui_blueprint)
 app.register_blueprint(bid, url_prefix='/api')
 
 

db.txt

@@ -1 +1,3 @@
-{'id': UUID('471fea1f-705c-4851-9a5b-df7bc2651428'), 'tender': 'test_tender', 'client': 'test_client', 'alias': 'test_alias', 'bid_date': '2023-06-21T00:00:00', 'bid_folder_url': 'test_folder_url', 'status': 'in_progress', 'links': {'self': '/bids/471fea1f-705c-4851-9a5b-df7bc2651428', 'questions': '/bids/471fea1f-705c-4851-9a5b-df7bc2651428/questions'}, 'was_successful': True, 'success': [{'phase': 2, 'has_score': True, 'score': 80, 'out_of': 100}], 'failed': {}, 'feedback': {'description': 'test_description', 'url': 'test_url'}, 'last_updated': '2023-06-23T11:16:59.404946'}{'id': UUID('0b695d23-5d4f-4cd7-b3a9-bb6497abd2f8'), 'tender': 'test_tender', 'client': 'test_client', 'alias': 'test_alias', 'bid_date': '2023-06-21T00:00:00', 'bid_folder_url': 'test_folder_url', 'status': 'in_progress', 'links': {'self': '/bids/0b695d23-5d4f-4cd7-b3a9-bb6497abd2f8', 'questions': '/bids/0b695d23-5d4f-4cd7-b3a9-bb6497abd2f8/questions'}, 'was_successful': True, 'success': [{'phase': 2, 'has_score': True, 'score': 80, 'out_of': 100}, {'phase': 2, 'has_score': True, 'score': 80, 'out_of': 100}], 'failed': {}, 'feedback': {'description': 'test_description', 'url': 'test_url'}, 'last_updated': '2023-06-23T11:17:23.593171'}
+
+{'id': UUID('471fea1f-705c-4851-9a5b-df7bc2651428'), 'tender': 'test_tender', 'client': 'test_client', 'alias': 'test_alias', 'bid_date': '2023-06-21T00:00:00', 'bid_folder_url': 'test_folder_url', 'status': 'in_progress', 'links': {'self': '/bids/471fea1f-705c-4851-9a5b-df7bc2651428', 'questions': '/bids/471fea1f-705c-4851-9a5b-df7bc2651428/questions'}, 'was_successful': True, 'success': [{'phase': 2, 'has_score': True, 'score': 80, 'out_of': 100}], 'failed': {}, 'feedback': {'description': 'test_description', 'url': 'test_url'}, 'last_updated': '2023-06-23T11:16:59.404946'}{'id': UUID('0b695d23-5d4f-4cd7-b3a9-bb6497abd2f8'), 'tender': 'test_tender', 'client': 'test_client', 'alias': 'test_alias', 'bid_date': '2023-06-21T00:00:00', 'bid_folder_url': 'test_folder_url', 'status': 'in_progress', 'links': {'self': '/bids/0b695d23-5d4f-4cd7-b3a9-bb6497abd2f8', 'questions': '/bids/0b695d23-5d4f-4cd7-b3a9-bb6497abd2f8/questions'}, 'was_successful': True, 'success': [{'phase': 2, 'has_score': True, 'score': 80, 'out_of': 100}, {'phase': 2, 'has_score': True, 'score': 80, 'out_of': 100}], 'failed': {}, 'feedback': {'description': 'test_description', 'url': 'test_url'}, 'last_updated': '2023-06-23T11:17:23.593171'}{'id': UUID('8fed99f8-3b7c-42ef-8c1f-fb3fe25ec039'), 'tender': 'test_tender', 'client': 'test_client', 'alias': 'test_alias', 'bid_date': '2023-06-21T00:00:00', 'bid_folder_url': 'test_folder_url', 'status': 'in_progress', 'links': {'self': '/bids/8fed99f8-3b7c-42ef-8c1f-fb3fe25ec039', 'questions': '/bids/8fed99f8-3b7c-42ef-8c1f-fb3fe25ec039/questions'}, 'was_successful': True, 'success': [{'phase': 2, 'has_score': True, 'score': 80, 'out_of': 100}], 'failed': {}, 'feedback': {'description': 'test_description', 'url': 'test_url'}, 'last_updated': '2023-06-23T15:57:34.571615'}{'id': UUID('96d69775-29af-46b1-aaf4-bfbdb1543412'), 'tender': 'test_tender', 'client': 'test_client', 'alias': 'test_alias', 'bid_date': '2023-06-21T00:00:00', 'bid_folder_url': 'test_folder_url', 'status': 'deleted', 'links': {'self': '/bids/96d69775-29af-46b1-aaf4-bfbdb1543412', 'questions': '/bids/96d69775-29af-46b1-aaf4-bfbdb1543412/questions'}, 'was_successful': True, 'success': [{'phase': 2, 'has_score': True, 'score': 80, 'out_of': 100}], 'failed': {}, 'feedback': {'description': 'test_description', 'url': 'test_url'}, 'last_updated': '2023-06-23T15:57:50.238595'}
+{'id': UUID('a1729d42-3962-47ce-b54b-2a93e879891c'), 'tender': 'test_tender', 'client': 'test_client', 'alias': 'test_alias', 'bid_date': '2023-06-21T00:00:00', 'bid_folder_url': 'test_folder_url', 'status': 'deleted', 'links': {'self': '/bids/a1729d42-3962-47ce-b54b-2a93e879891c', 'questions': '/bids/a1729d42-3962-47ce-b54b-2a93e879891c/questions'}, 'was_successful': True, 'success': [{'phase': 2, 'has_score': True, 'score': 80, 'out_of': 100}], 'failed': {}, 'feedback': {'description': 'test_description', 'url': 'test_url'}, 'last_updated': '2023-06-27T14:05:17.623827'}{'id': UUID('ab7bec38-f866-46ba-8e94-e85fec951326'), 'tender': 'Business Intelligence and Data Warehousing', 'client': 'Office for National Statistics', 'alias': 'ONS', 'bid_date': '2023-06-21T00:00:00', 'bid_folder_url': 'https://organisation.sharepoint.com/Docs/dummyfolder', 'status': 'deleted', 'links': {'self': '/bids/ab7bec38-f866-46ba-8e94-e85fec951326', 'questions': '/bids/ab7bec38-f866-46ba-8e94-e85fec951326/questions'}, 'was_successful': True, 'success': [{'phase': 2, 'has_score': True, 'score': 80, 'out_of': 100}, {'phase': 2, 'has_score': True, 'score': 80, 'out_of': 100}], 'failed': {}, 'feedback': {'description': '', 'url': ''}, 'last_updated': '2023-06-27T16:51:58.932142'}{'id': UUID('dfff0088-0ae0-4c80-8a32-e70c166453c2'), 'tender': 'Business Intelligence and Data Warehousing', 'client': 'Office for National Statistics', 'alias': 'ONS', 'bid_date': '2023-06-21T00:00:00', 'bid_folder_url': 'https://organisation.sharepoint.com/Docs/dummyfolder', 'status': 'deleted', 'links': {'self': '/bids/dfff0088-0ae0-4c80-8a32-e70c166453c2', 'questions': '/bids/dfff0088-0ae0-4c80-8a32-e70c166453c2/questions'}, 'was_successful': True, 'success': [{'phase': 2, 'has_score': True, 'score': 80, 'out_of': 100}, {'phase': 2, 'has_score': True, 'score': 80, 'out_of': 100}, {'phase': 2, 'has_score': True, 'score': 80, 'out_of': 100}], 'failed': {}, 'feedback': {'description': '', 'url': ''}, 'last_updated': '2023-06-27T16:52:00.527900'}

requirements.txt

@@ -7,3 +7,4 @@ MarkupSafe==2.1.3
 Werkzeug==2.3.6
 pip==23.1.2
 pytest==7.3.2
+flask_swagger_ui==4.11.1

static/swagger_config.yml

@@ -0,0 +1,285 @@
+# ---
+openapi: 3.0.3
+# --------------------------------------------
+# Info
+info:
+  title: Bids API
+  description: | 
+    This is a API for the Bids API.
+    You can find out more about
+    this API at [GitHub](https://github.com/methods/tdse-accessForce-bids-api).
+    You can now help us improve the API whether it's by making changes to the definition itself or to the code.
+    That way, with time, we can improve the API in general, and expose some of the new features in OAS3.
+    Some useful links:
+    - [API repository](https://github.com/methods/tdse-accessForce-bids-api)
+  version: 1.0.0
+  termsOfService: 'https://github.com/methods/tdse-accessForce-bids-api'
+  contact:
+    email: accessForce@example.com
+  license:
+    name: MIT License
+    url: 'https://github.com/methods/tdse-accessForce-bids-api/blob/develop/LICENSE.md'
+# --------------------------------------------
+# Server
+servers:
+  - url: 'http://localhost:3000/api/'
+    description: Local server
+# --------------------------------------------
+# Tags
+tags:
+  - name: bids
+    description: Everything about BIDS
+    externalDocs:
+      description: Find out more
+      url: example.com
+  - name: questions
+    description: Everything about QUESTIONS
+    externalDocs:
+      description: Find out more
+      url: example.com
+# --------------------------------------------
+# Paths
+paths:
+  /bids:
+# --------------------------------------------
+    get:
+      tags:
+        - bids
+      summary: Returns all bids
+      description: Returns all bids
+      responses:
+        '200':    # status code
+          description: A JSON array of bids
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Bid'
+# --------------------------------------------
+    post:
+      tags:
+        - bids
+      summary: Create a new bid
+      description: Create a new bid
+      operationId: post_bid
+      requestBody:
+        $ref: '#/components/requestBodies/Bid'        
+        required: true
+      responses:
+        '201':
+          description: Created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Bid'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+# --------------------------------------------
+# Components
+components:
+# --------------------------------------------
+# Schemas
+  schemas:
+    Bid:
+      description: Bid document
+      type: object
+      required:
+        - id
+        - tender
+        - client
+        - bid_date
+        - status
+        - links
+        - last_updated
+      properties:
+        tender:
+          type: string
+          example: 'Business Intelligence and Data Warehousing'
+        last_updated:
+          type: string
+          example: "2023-06-27T14:05:17.623827"
+        failed:
+          type: object
+          $ref: '#/components/schemas/Phase'
+          example: '#/components/schemas/Phase'
+        feedback:
+          type: object
+          $ref: '#/components/schemas/Feedback'
+        success:
+          type: array
+          items:
+            type: object
+            $ref: '#/components/schemas/Phase'
+        alias:
+          type: string
+          example: 'ONS'
+        client:
+          type: string
+          example: 'Office for National Statistics'
+        links:
+          type: object
+          required:
+            - questions
+            - self
+          properties:
+            questions:
+              $ref: '#/components/schemas/QuestionsLink'
+            self:
+              $ref: '#/components/schemas/SelfLink'
+        id:
+          type: string
+          format: uuid
+          example: "UUID('471fea1f-705c-4851-9a5b-df7bc2651428')"
+        bid_date:
+          type: string
+          format: ISO-8601
+          example: '2023-06-21T00:00:00'
+        status:
+          type: string
+          description: Bid Status
+          example: in_progress
+          enum:
+            - IN_PROGRESS
+            - DELETED
+            - COMPLETED
+        was_successful:
+          type: boolean
+          example: true
+# --------------------------------------------
+    Phase:
+      description: Phase information
+      type: object
+      required:
+        - phase
+        - has_score
+      properties:
+        phase:
+          description: Phase of bid
+          type: integer
+          example: 2
+        score:
+          description: Score achieved at phase
+          type: integer
+          example: 22
+        has_score:
+          description: Score information available or not
+          type: boolean
+          example: true
+        out_of:
+          description: Maximum score
+          type: integer
+          example: 36
+# --------------------------------------------
+    Feedback:
+      description: Feedback from client (if provided)
+      type: object
+      required:
+        - feedback_url
+        - feedback_description
+      properties:
+        feedback_url:
+          description: Link to feedback
+          type: string
+          example: 'https://organisation.sharepoint.com/Docs/dummyfolder/feedback'
+        feedback_description:
+          description: Summary of feedback
+          type: string
+          example: 'Feedback from client in detail'
+# --------------------------------------------
+    QuestionsLink:
+      description: A link to a collection of questions for a bid
+      type: string
+      example: 'https://localhost:3000/api//bids/96d69775-29af-46b1-aaf4-bfbdb1543412/questions'
+# --------------------------------------------
+    SelfLink:
+      description: A link to the current resource
+      type: string
+      example: 'https://localhost:3000/api/bids/471fea1f-705c-4851-9a5b-df7bc2651428'
+# --------------------------------------------
+    BidRequestBody:
+      type: object
+      required:
+        - tender
+        - client
+        - bid_date
+      properties:
+        tender:
+          description: Name of tender
+          type: string          
+        bid_folder_url:
+          description: Link to bid info
+          type: string        
+        feedback:
+          description: Feedback info
+          type: object
+          $ref: '#/components/schemas/Feedback'        
+        client:
+          description: Name of client tendering
+          type: string
+        alias:
+          description: Client alias
+          type: string
+        bid_date:
+          description: Date of bid
+          type: string
+        failed_phase:
+          description: Failed phase info
+          type: object
+          $ref: '#/components/schemas/Phase'
+        success_list:
+          description: List of successful phases
+          type: array
+          items:
+            $ref: '#/components/schemas/Phase'
+# --------------------------------------------
+# Request bodies
+  requestBodies:
+    Bid:
+      description: Bid object to be added to collection
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/BidRequestBody'
+          examples:
+            200 Created:
+              summary: 200 Created
+              value:
+                tender: 'Business Intelligence and Data Warehousing'
+                bid_folder_url: 'https://organisation.sharepoint.com/Docs/dummyfolder'
+                feedback:
+                  feedback_url: 'https://organisation.sharepoint.com/Docs/dummyfolder/feedback'
+                  feedback_description: 'Feedback from client in detail'
+                client: 'Office for National Statistics'
+                alias: 'ONS'
+                bid_date: '21-06-2023'
+            400 Bad Request:
+              summary: 400 Bad Request
+              value:
+                bid_folder_url: 'https://organisation.sharepoint.com/Docs/dummyfolder'
+                feedback:
+                  feedback_url: 'https://organisation.sharepoint.com/Docs/dummyfolder/feedback'
+                  feedback_description: 'Feedback from client in detail'
+                client: 'Office for National Statistics'
+                alias: 'ONS'
+                bid_date: '21-06-2023'
+# --------------------------------------------
+# Error responses
+  responses:
+    BadRequest:
+      description: Bad Request Error
+      content:
+        text/plain:
+          schema:
+            type: string
+            example: Missing mandatory field
+    InternalServerError:
+      description: Internal Server Error
+      content:
+        text/plain:
+          schema:
+            type: string
+            example: Could not connect to a database
+# --------------------------------------------