Implement Swagger UI for Endpoint Documentation in Development Environment

[ArsalonAI]

Description

We need to integrate Swagger UI into the development environment of our agentic AI framework. This will provide a clear and interactive documentation interface for the available endpoints, improving collaboration between developers, reducing onboarding time, and ensuring that API behavior is well-documented and easily testable.

Objectives

• Integrate Swagger UI into the development environment.
• Automatically generate API documentation from the existing endpoint definitions.
• Ensure compatibility with the framework's current architecture (e.g., TypeScript, Node.js/Express, etc.).
• Allow developers to test endpoints directly from the Swagger UI interface.

Install Swagger Dependencies

• Add the required Swagger dependencies (swagger-ui-express, swagger-jsdoc, etc.) to the project.
• Verify that the dependencies are correctly installed and compatible with the existing framework.

Create Swagger Configuration

• Write the Swagger configuration file (swagger.json or equivalent) to define API metadata, available endpoints, schemas, and response formats.
• Ensure the configuration supports dynamic endpoint generation using decorators or annotations, if applicable.

Setup Swagger Middleware

• Add middleware in the dev environment to serve Swagger UI (e.g., /api-docs route).
• Configure the middleware to load the Swagger configuration file dynamically from the endpoint definitions.

Annotate Endpoints

• Use decorators or inline comments to document the existing endpoints, including request parameters, response schemas, and error codes.
• Ensure annotations follow the OpenAPI Specification (OAS) format for Swagger compatibility.

Test the Integration

• Verify that all endpoints are correctly documented and testable through the Swagger UI.
• Ensure that dynamic changes in the endpoint structure or new endpoints are reflected in the documentation.

Optimize for Agentic AI Framework

• Add any framework-specific metadata to the Swagger documentation, such as details about agent behavior, capabilities, or token-based authentication.
• Ensure that AI-related endpoints (e.g., for interacting with smart contracts or agent coordination) are properly described.

Acceptance Criteria:

• Swagger UI is accessible at /api-docs in the development environment.
  All existing endpoints are documented and testable in the Swagger UI interface.
• Configuration dynamically updates as new endpoints are added.
• The system provides clear and accurate request/response examples for each endpoint.
• The Swagger UI includes notes for agentic AI-specific features like token interactions and multi-agent coordination.

[ArsalonAI]

@VisionOra you mentioned this is completed (on ticket #196 )

Please add a PR here so that we can isolate that update and tag @monilpat to review it.

[VisionOra]

@ArsalonAmini2024 i've created PR for both #292 and #295 already