[Feature]: Add OpenAPI Schema Export and Interactive Swagger Documentation

[adepat06]

Problem Statement

While exploring Eagle and reviewing the repository, I could not find any interactive API documentation or a clearly exposed OpenAPI/Swagger interface for the backend services.

At the moment, contributors often need to look through route definitions and source files to understand available endpoints, request parameters, and response formats. This can make onboarding and development slower, especially for contributors working on integrations, testing, frontend features, or backend services.

Providing interactive API documentation would make it easier to discover and test endpoints, improve the developer experience, and help new contributors understand the system more quickly.

Proposed Solution

A possible solution would be to expose interactive API documentation using FastAPI's built-in OpenAPI support.

This could include:

• Enabling Swagger UI (/docs) for exploring available endpoints.
• Providing an OpenAPI schema (openapi.json) that can be used for integrations and API testing.
• Adding summaries, descriptions, and response models to important routes where needed.
• Optionally enabling ReDoc (/redoc) for a cleaner documentation view.

With this in place, contributors and developers would be able to view available endpoints, understand request/response formats, and test APIs directly from the browser without having to inspect the source code for every route.

Affected Component

Backend API (FastAPI — apps/backend/)

Estimated Difficulty

🟡 Intermediate — Requires understanding of one service

Alternatives Considered

Currently, contributors can inspect route definitions directly in the source code or rely on existing documentation to understand how the APIs work.

Another option would be to maintain separate API documentation manually, but this can easily become outdated as endpoints evolve over time.

Using FastAPI's built-in OpenAPI support would provide automatically generated documentation that stays synchronized with the actual API implementation.

Additional Context

While exploring the repository, I searched for references to Swagger/OpenAPI support (e.g., swagger, openapi, docs_url, and redoc) but could not find an existing implementation or related issue.

FastAPI already provides built-in support for OpenAPI schema generation and interactive documentation, which could make this enhancement relatively straightforward while significantly improving the developer experience.

Reference:
https://fastapi.tiangolo.com/features/

Contribution

• I would like to implement this feature and submit a PR.

Checklist

• I have searched existing issues and this is not a duplicate.
• I have read the CONTRIBUTING.md guidelines.

[adepat06]

Hi @Devnil434,

I would like to work on this feature under GSSoC 2026.

While exploring the repository, I noticed that I could not find an exposed OpenAPI/Swagger interface or related API documentation. I believe this enhancement would improve developer onboarding, API discoverability, and testing experience for contributors.

If the proposal looks good, please assign this issue to me. I would be happy to work on the implementation and submit a PR.

Thank you!

[adepat06]

Hi @Devnil434,

While working on this issue, I investigated the backend implementation in more detail.

The FastAPI application already appears to be configured with OpenAPI support enabled, and the README references /docs as the API documentation endpoint. Route handlers also use response models and docstrings that would be reflected in generated documentation.

I attempted to verify this locally, but the backend currently fails to start due to unrelated issues (including an INGEST_COUNTER import error), so I was unable to fully validate the /docs endpoint.

Based on the current codebase, it seems Swagger/OpenAPI integration may already be present. Could you please confirm whether this issue should be closed, or whether the intended scope is to further improve the existing API documentation (summaries, descriptions, examples, etc.)?

Thank you.