Add Swagger Documentation to finesse-backend

[k-allagbe]

To improve the clarity and accessibility of the Finesse Backend's API, we are introducing Swagger documentation. This will offer a structured and interactive interface for our API, making it easier for developers to understand and interact with our system.

Tasks

• Investigate how to best integrate Swagger with finesse-backend.
• Install Swagger-related dependencies.
• Configure Swagger to document existing Flask routes.
• Verify that the Swagger UI is properly displaying and interacting with our API endpoints.

Acceptance Criteria

1. Swagger UI displays and operates as expected.
2. All endpoints are accurately documented.

Architectural Design Options:

There are multiple ways to create Swagger documentation with the flask library, each with its own considerations and trade-offs.

flask_swagger_ui :

---

Description:
flask_swagger_ui is a library that generates Swagger documentation for Flask applications. It relies on a static OpenAPI specification (json) file to display API documentation.

Advantages:

• Straightforward setup: Setting up flask_swagger_ui is relatively simple, as it only requires pointing to a static OpenAPI specification file.
• Non-intrusive: The code does not need to be modified, only need to add the new part
• Editor online: Swagger provides an online editor to simplify the creation of the json file

Disadvantages:

• Static documentation: The documentation is static and may not automatically update with changes in the code, leading to potential synchronization issues.
• Manual updates: Any modifications to the API require manual updates to the json file, increasing the risk of errors, inconsistencies and time consumption.
• Limited community support: The community support might be limited compared to more widely adopted alternatives.

flask_restplus :

---

Description:
flask_restplus is an extension for Flask that builds on top of flask_restful to simplify the creation of RESTful APIs. It includes built-in Swagger support and additional features for API documentation.

Advantages:

• Integrated Swagger support: flask_restplus provides built-in Swagger support, making it easier to generate and maintain API documentation.
• Dynamic documentation: Swagger documentation is generated dynamically from the code, ensuring that the documentation stays in sync with the API implementation.
• Namespace and resource support: It introduces the concepts of namespaces and resources, aiding in the organization and modularization of API code.
• Potential time savings: The dynamic nature of documentation generation in flask_restplus can potentially save time
• Active community support: Being a popular choice, flask_restplus benefits from an active and supportive community.

Disadvantages:

• Intrusive code: Requires to modify the current structure with namespaces and resources
• Less dynamic documentation: While it generates Swagger documentation, it might be less dynamic and often requires additional annotations to provide comprehensive details.

flask_restx :

---

Description:
flask_restx is an extension of flask_restful that adds support for Swagger generation. While keeping the same advantages than flask_restplus, it introduces better documentation.

Advantages:

• Better dynamic documentation: Provides a more dynamic Swagger documentation generated directly from the code, ensuring automatic synchronization with API changes.
• Direct code annotations: Allows for adding Swagger annotations directly in the code, simplifying documentation maintenance.

Disadvantages:

• Initial learning curve: Transitioning from flask_restplus to flask_restx may involve some adaptation and a steeper initial learning curve.

Consideration of these architectural design options will help in making an informed decision based on the specific requirements and preferences of the project.

Close PR:

• closes Add Swagger Documentation to finesse-backend #27