🔥 feat: Add OpenAPI middleware

[gaby]

Summary

• auto-generate openapi.json file from app router
• support per-operation IDs, tags, and deprecation metadata in the OpenAPI middleware
• serve specs from grouped routes and verify raw JSON output in new tests
• assert middleware JSON matches a fixture to guard against regressions

Fixes #2347 #1297 #3118

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

✨ Finishing touches

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch 2025-08-21-14-48-18

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

❌ Patch coverage is 80.62157% with 106 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.96%. Comparing base (8fc239f) to head (9b1a022).
⚠️ Report is 59 commits behind head on main.

Files with missing lines	Patch %	Lines
middleware/openapi/openapi.go	79.65%	41 Missing and 18 partials ⚠️
router.go	53.12%	30 Missing ⚠️
app.go	87.68%	12 Missing and 5 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3702      +/-   ##
==========================================
- Coverage   91.81%   90.96%   -0.85%     
==========================================
  Files         114      115       +1     
  Lines       11498    12344     +846     
==========================================
+ Hits        10557    11229     +672     
- Misses        681      824     +143     
- Partials      260      291      +31     

Flag	Coverage Δ
unittests	90.96% <80.62%> (-0.85%)	⬇️

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

☔ View full report in Codecov by Sentry.
📢 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.

[gaby]

/gemini review

[gemini-code-assist]

Warning

Gemini encountered an error creating the review. You can try again by commenting /gemini review.

[gaby]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a new OpenAPI middleware for auto-generating API specifications. The implementation is solid, with good test coverage and documentation. I've identified a potential improvement to prevent the middleware from documenting its own endpoint in the generated spec, which would make the output cleaner for API consumers. I also found a minor formatting issue in the documentation. Overall, this is a great feature addition.

[gemini-code-assist]

There's a minor formatting issue here. The nil value is not aligned with the other values in the ConfigDefault struct example.

Suggested change

	Operations: nil,
	Operations: nil,

[ReneWerner87]

nice feature, thx @gaby
can you update and convert the DRAFT to READY (when it is ready for you)