Refine API documentation

[juhoinkinen]

Reasons for creating this PR

The interactive Swagger API documentation (/docs endpoint) has some flaws and potential for improvement:

1. It shows "default" as a subtitle for all the methods
2. The root / is included in the methods list, while it returns the static index.html page and should not be included in the API endpoint list(?) (/v0/ returns API version information)
3. The example value of /v0/projects is "string" while in reality the response is a JSON object
4. A curl example for how to upload a file to /extract method would ease typical use

Link to relevant issue(s), if any

• Closes #

Description of the changes in this PR

1. Give a name for the subtitle: "v0"
2. Hide root / using include_in_schema=False
3. The example value is now shown as

   {
     "additionalProp1": {}
   }
   

4. A curl example is added to for the extract method:

   curl -X POST "http://localhost:8000/v0/projects/my_project/extract" -F "files=@/path/to/document.pdf"
   

Instructions how to test this PR

Run

uv run uvicorn bibra.main:app --reload

and take a look.

Known problems or uncertainties in this PR

Should the static index.html page be included in the API endpoint list?

Checklist

• I have added tests that show that the new code works, or tests are not relevant for this PR (e.g. only HTML/CSS changes)
• The PR doesn't introduce unintended code changes (e.g. empty lines or useless reindentation)

Disclosure of AI Tool Usage

Please indicate AI use by choosing the most suitable TLP:AI category below and removing the irrelevant categories from the list. AI:ORANGE is the minimum level for merging.

• 🟢 AI:GREEN AI-assisted. Author drove the process, AI used as a tool (autocomplete,
  Describe the AI tool(s) you used:

Describe the AI tool(s) you used:

• Zoo Code with Qwen3.6-35B-A3B

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.50%. Comparing base (ef35240) to head (2f81267).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #114   +/-   ##
=======================================
  Coverage   98.50%   98.50%           
=======================================
  Files          13       13           
  Lines         536      536           
=======================================
  Hits          528      528           
  Misses          8        8           

Flag	Coverage Δ
unittests	98.50% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull request overview

This PR refines the FastAPI/Swagger documentation for the BIBRA API by improving endpoint grouping and visibility, and by adding clearer endpoint descriptions/examples.

Changes:

• Tag all v0 API routes with tags=["v0"] to avoid the default Swagger group.
• Hide the HTML root endpoint (/) from the OpenAPI schema.
• Add OpenAPI summaries and a curl usage example for the extract endpoint.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
bibra/main.py	Hides the static HTML root route from Swagger via include_in_schema=False.
bibra/api/v0/routes.py	Adds v0 tagging, adds summaries, and adds a curl example to improve interactive docs.

Suppressed comments (1)

bibra/api/v0/routes.py:47

• response_model=dict for /projects makes the OpenAPI contract too loose and hides the actual response structure ({"projects": [{"id","name","description"}, ...]}). This also weakens schema-based testing (e.g. Schemathesis) because almost any object would validate. Prefer an explicit response model that names the projects field and its item shape.

@router.get("/projects", response_model=dict, summary="List projects")
async def list_projects(registry: Annotated[ProjectRegistry, Depends(get_registry)]):
    """Return a list of configured projects."""
    try:
        projects = registry.list_projects()
    except ConfigError as e:
        logger.exception("Configuration error")
        raise HTTPException(status_code=500, detail=str(e))
    return {"projects": projects}

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.