OpenAPI: wire utoipa in presentation #14

New Issue

GKaszewski · 2026-07-12T05:49:42Z

GKaszewski commented

2026-07-12 05:49:42 +00:00

Parent

What to build

Wire utoipa properly in the presentation crate to generate and serve OpenAPI documentation. The api-types crate already has #[derive(ToSchema)] on all DTOs. The presentation crate needs to merge these into a complete OpenAPI spec and serve it.

Add a GET /api/docs endpoint that serves the OpenAPI JSON. Optionally serve a Swagger UI or Scalar UI at GET /api/docs/ui.

Use utoipa's #[utoipa::path] attribute on handler functions to document each endpoint's request/response types, parameters, and status codes.

Acceptance criteria

GET /api/docs returns a valid OpenAPI 3.x JSON spec
All API endpoints are documented in the spec with correct request/response schemas
Path parameters, query parameters, and request bodies are documented
Response status codes are documented (200, 201, 204, 400, 401, 403, 404, 409, 500)
A UI is available at GET /api/docs/ui for interactive browsing
Schemas reference the api-types crate's ToSchema derives

Blocked by

None — can start immediately

## Parent #2 ## What to build Wire utoipa properly in the presentation crate to generate and serve OpenAPI documentation. The api-types crate already has `#[derive(ToSchema)]` on all DTOs. The presentation crate needs to merge these into a complete OpenAPI spec and serve it. Add a `GET /api/docs` endpoint that serves the OpenAPI JSON. Optionally serve a Swagger UI or Scalar UI at `GET /api/docs/ui`. Use utoipa's `#[utoipa::path]` attribute on handler functions to document each endpoint's request/response types, parameters, and status codes. ## Acceptance criteria - [ ] `GET /api/docs` returns a valid OpenAPI 3.x JSON spec - [ ] All API endpoints are documented in the spec with correct request/response schemas - [ ] Path parameters, query parameters, and request bodies are documented - [ ] Response status codes are documented (200, 201, 204, 400, 401, 403, 404, 409, 500) - [ ] A UI is available at `GET /api/docs/ui` for interactive browsing - [ ] Schemas reference the api-types crate's ToSchema derives ## Blocked by None — can start immediately

GKaszewski added the ready-for-agent label 2026-07-12 05:49:42 +00:00

GKaszewski referenced this issue from a commit

2026-07-12 13:13:34 +00:00

wire utoipa OpenAPI: #[utoipa::path] on all handlers, Scalar UI (#14)

GKaszewski closed this issue

2026-07-12 13:13:45 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: GKaszewski/k-tv#14