docs(api): refresh OpenAPI spec and add API port proposals#316
docs(api): refresh OpenAPI spec and add API port proposals#316
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9dfd9f3834
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| }, | ||
| "servers": [ | ||
| { | ||
| "url": "http://localhost:5003", |
There was a problem hiding this comment.
Hard-coding http://localhost:5003 as the only server makes Swagger "Try it out" fail for any non-local deployment context (e.g., container, staging VM, or another host on the network), because the browser will target the viewer's own localhost rather than the running API. Since this spec is served by the app itself (/api/docs -> /static/swagger.json), a relative server URL (or multiple environment entries) is needed to keep the documented endpoints usable outside local dev.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Summary
- Addressed the PR review feedback by replacing the hardcoded OpenAPI server URL (
http://localhost:5003) with a relative URL ("/"), so Swagger “Try it out” resolves against the currently served host instead of the viewer’s localhost. backend/sbs_server/app/static/swagger.jsonL8-L12 - Updated the server description to explicitly state cross-environment compatibility (local/container/deployed). backend/sbs_server/app/static/swagger.jsonL11
Testing
- ✅
python -m json.tool backend/sbs_server/app/static/swagger.json >/dev/null && echo OK - ✅
git diff -- backend/sbs_server/app/static/swagger.json
Also completed the requested follow-up workflow:
- Committed changes:
docs(api): use relative OpenAPI server URL - Created a follow-up PR via
make_prwith title: docs(api): make OpenAPI server URL deployment-agnostic.
|
Azure Static Web Apps: Your stage site is ready! Visit it here: https://witty-hill-08172a210-316.centralus.5.azurestaticapps.net |
|
Azure Static Web Apps: Your stage site is ready! Visit it here: https://witty-hill-08172a210-316.centralus.5.azurestaticapps.net |
|
Azure Static Web Apps: Your stage site is ready! Visit it here: https://witty-hill-08172a210-316.centralus.5.azurestaticapps.net |
1 participant
Motivation
Description
backend/sbs_server/app/static/swagger.jsonwith a consistent OpenAPI 3.0.3 document that describes the current endpoints and server URL (http://localhost:5003) and adds reusable request/response schemas such asUploadResourceRequest,UploadResponse,ErrorResponse,GoldenGateRequest, andPuduBuildRequest.GET /api/status,POST /api/uploadResource,POST /api/uploadExperiment,POST /sbol_2_build_golden_gate,POST /api/build_puduandPOST /api/inspect_request, and marked existing placeholders that return501(assembly/transformation) with clear descriptions.backend/API_PORT_PROPOSALS.md, a short design doc listing proposed endpoints to add (/api/version,/api/ready,/api/capabilities,/api/validate/*, and/api/jobs/*) with example payloads and a recommended rollout order.Testing
python -m json.tool backend/sbs_server/app/static/swagger.jsonwhich succeeded without errors.Codex Task