[API-QA] Add missing Swagger documentation for Shipments endpoints

[kingksjo]

Domain: Documentation

---

Issue [API-QA] Add missing Swagger documentation for Shipments endpoints

Tier: 🟢 Easy

Description:

• Problem: The docs/swagger.yaml spec does not document the Shipments module endpoints (POST /api/shipments, GET /api/shipments, GET /api/shipments/:id, POST /api/shipments/:id/proof). Frontend developers and API consumers have no authoritative contract for these critical routes.
• Implementation: Add full OpenAPI path definitions under /api/shipments in docs/swagger.yaml including request bodies, query params, response schemas (200, 401, 403, 404), and auth guards (bearerAuth). Reference the existing Shipment component schema.

Dependencies:

• Depends on None

Acceptance Criteria:

• POST /api/shipments is fully documented with request body and 201 response.
• GET /api/shipments is documented with query params, pagination meta, and 200 response.
• GET /api/shipments/:id is documented with path param and 404 case.
• POST /api/shipments/:id/proof is documented with multipart file upload and 200 response.
• All shipment endpoints correctly declare security: [bearerAuth: []] where applicable.

Testing Requirements:

• Swagger UI renders all new shipment paths without YAML syntax errors.
• npm run build passes with zero warnings.
• Spot-check that documented request/response shapes match the actual controller behavior.

PR Checklist:

• Branch is named conventionally (e.g., docs/issue-56-shipments-swagger).
• npm run lint and npm run build pass with zero warnings.

[TheShnider]

@TheShnider has applied to work on this issue as part of the Stellar Wave Program's 5th wave.

Hi. I have reviewed this issue and would like to work on it.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @TheShnider to this issue.

[Itodo-S]

@Itodo-S has applied to work on this issue as part of the Stellar Wave Program's 5th wave.

Please let me work on this issue; I can handle it.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Itodo-S to this issue.

[Mehcee]

@Mehcee has applied to work on this issue as part of the Stellar Wave Program's 5th wave.

I would like to work on this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Mehcee to this issue.

[drips-wave]

Congratulations, @Mehcee! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 2, 2026.

🧑‍💻 @Mehcee: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊