feat(server): expose openapi and swagger endpoints on http server

[ManthanNimodiya]

What & Why

Permify did not expose its OpenAPI/Swagger JSON specifications over HTTP, making integration with API gateways, Swagger UI, and developer portals cumbersome.
This embeds the specifications and registers GET endpoints to serve them directly from the HTTP gateway.

Changes

• Added embedded definitions in docs/docs.go for OpenAPI 3.0 and Swagger 2.0 JSON specifications.
• Registered /openapi.json, /swagger.json, and /docs/... endpoints on runtime.ServeMux in internal/servers/openapi.go and internal/servers/server. go.
• Added unit tests in internal/servers/openapi_test.go to validate HTTP response codes, headers, and JSON schemas.

Checklist

• Code builds locally (go build ./...)
• Relevant tests pass (go test -v ./internal/servers/...)
• Resolves Add an endpoint to expose openapi #1714

Summary by CodeRabbit

• Documentation

  • OpenAPI 3.0 JSON documentation is now available at /openapi.json.
  • The previous Swagger and alternate OpenAPI documentation endpoints are no longer available.
  • The published specification identifies the Permify API and is served as JSON.

• Tests

  • Added coverage confirming the OpenAPI endpoint response and metadata, along with expected handling of unregistered paths.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 0eb2f792-da0b-4e9c-b10d-324cc550e4b2

📥 Commits

Reviewing files that changed from the base of the PR and between 64c64c2 and e8347d1.

📒 Files selected for processing (3)

• docs/docs.go
• internal/servers/openapi.go
• internal/servers/openapi_test.go

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

---

📝 Walkthrough

Walkthrough

The change embeds the OpenAPI 3.0 specification, exposes it at /openapi.json, removes older specification endpoints, and validates registration and responses during gateway setup.

Changes

OpenAPI exposure

Layer / File(s)	Summary
Embed OpenAPI specification docs/docs.go	The docs package exports embedded OpenAPI 3.0 JSON and removes the Swagger and OpenAPI 2.0 variables.
Register and validate the OpenAPI endpoint internal/servers/openapi.go, internal/servers/server.go, internal/servers/openapi_test.go	The gateway registers GET /openapi.json, Container.Run propagates registration errors, and tests validate the JSON response and 404 handling.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant ContainerRun
  participant RegisterOpenAPIHandlers
  participant ServeMux
  participant OpenAPIJSON
  ContainerRun->>RegisterOpenAPIHandlers: register OpenAPI handler
  RegisterOpenAPIHandlers->>ServeMux: register GET /openapi.json
  ServeMux->>OpenAPIJSON: retrieve embedded JSON
  OpenAPIJSON-->>ServeMux: return specification bytes
  ServeMux-->>ContainerRun: serve application/json response

Loading

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	The title correctly identifies the HTTP server and OpenAPI exposure, but it incorrectly states that Swagger endpoints are exposed. The changes expose only /openapi.json and remove Swagger endpoints.	Change the title to describe the actual primary change, such as feat(server): expose OpenAPI specification at /openapi.json.
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 4 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	Issue #1714 requires a simple HTTP endpoint that exposes the OpenAPI specification in JSON format. RegisterOpenAPIHandlers registers GET /openapi.json and serves docs.OpenAPIJSON. `Container.Run…
Out of Scope Changes check	✅ Passed	The reviewed changes embed the OpenAPI specification, register the requested /openapi.json endpoint, integrate it with the HTTP gateway, and test the endpoint. The pull request removes the previousl…

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Create a new PR

---

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.}

[codecov]

Codecov Report

❌ Patch coverage is 75.00000% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 76.28%. Comparing base (4ab48bd) to head (e8347d1).
⚠️ Report is 2 commits behind head on master.

Files with missing lines	Patch %	Lines
internal/servers/server.go	0.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #3211      +/-   ##
==========================================
- Coverage   76.29%   76.28%   -0.01%     
==========================================
  Files          83       84       +1     
  Lines        9215     9223       +8     
==========================================
+ Hits         7030     7035       +5     
- Misses       1635     1638       +3     
  Partials      550      550              

☔ 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.