Add Swagger API docs page #49

New issue

Closed

opened 2026-05-22 09:46:57 -05:00 by erik · 2 comments

erik commented

2026-05-22 09:46:57 -05:00

Owner

Copy link

Goal

Add a small manually testable Swagger UI page for the Slugkit OpenAPI document.

Requirements

Add an API docs route that renders Swagger UI for the existing OpenAPI document.
Follow the reference implementation pattern from ~/Private/code/github/evcraddock/erikcraddock.me: use @hono/swagger-ui and point the UI at ./openapi.json.
Mount docs under the existing API v1 surface, e.g. GET /api/v1/docs.
Keep the OpenAPI JSON document as the source of truth.
Keep this as a small vertical slice with no unrelated API/schema changes.
Follow docs/CONTRIBUTING.md and docs/CODE_STANDARDS.md.

Acceptance criteria

GET /api/v1/docs returns HTTP 200 HTML.
The docs HTML contains Swagger UI assets/initialization.
The docs page points at ./openapi.json.
Existing GET /api/v1/openapi.json remains available and parseable.
Tests cover the docs route.
README or template docs mention the API docs URL.
Relevant lint/test checks pass.

Dependencies

task-c272cbda

## Goal Add a small manually testable Swagger UI page for the Slugkit OpenAPI document. ## Requirements - Add an API docs route that renders Swagger UI for the existing OpenAPI document. - Follow the reference implementation pattern from `~/Private/code/github/evcraddock/erikcraddock.me`: use `@hono/swagger-ui` and point the UI at `./openapi.json`. - Mount docs under the existing API v1 surface, e.g. `GET /api/v1/docs`. - Keep the OpenAPI JSON document as the source of truth. - Keep this as a small vertical slice with no unrelated API/schema changes. - Follow `docs/CONTRIBUTING.md` and `docs/CODE_STANDARDS.md`. ## Acceptance criteria - [ ] `GET /api/v1/docs` returns HTTP 200 HTML. - [ ] The docs HTML contains Swagger UI assets/initialization. - [ ] The docs page points at `./openapi.json`. - [ ] Existing `GET /api/v1/openapi.json` remains available and parseable. - [ ] Tests cover the docs route. - [ ] README or template docs mention the API docs URL. - [ ] Relevant lint/test checks pass. ## Dependencies - task-c272cbda

erik added the

labels

2026-05-22 09:46:57 -05:00

erik commented

2026-05-22 10:02:55 -05:00

Author

Owner

Copy link

Synced from todu comment by @todu on 2026-05-22T15:02:18.024Z

PR Review: Approved

PR: #50

Summary

Reviewed PR #50 at commit 38f5d0f. The PR adds the requested Swagger UI vertical slice: GET /api/v1/docs is registered under the existing API v1 surface, uses @hono/swagger-ui, points at the existing OpenAPI source of truth via ./openapi.json, includes route tests, and documents the new API docs URL.

Acceptance Criteria

GET /api/v1/docs returns HTTP 200 HTML.
The docs HTML contains Swagger UI assets/initialization.
The docs page points at ./openapi.json.
Existing GET /api/v1/openapi.json remains available and parseable.
Tests cover the docs route.
README or template docs mention the API docs URL.
Relevant lint/test checks pass: make check, ./scripts/pre-pr.sh, manual Swagger UI smoke, and Forgejo CI all passed.

Blocking Issues

None.

Warnings

None.

Verdict

Approved for merge.

_Synced from todu comment by @todu on 2026-05-22T15:02:18.024Z_ ## PR Review: Approved PR: https://forge.caradoc.com/erik/slugkit/pulls/50 ### Summary Reviewed PR #50 at commit `38f5d0f`. The PR adds the requested Swagger UI vertical slice: `GET /api/v1/docs` is registered under the existing API v1 surface, uses `@hono/swagger-ui`, points at the existing OpenAPI source of truth via `./openapi.json`, includes route tests, and documents the new API docs URL. ### Acceptance Criteria - [x] `GET /api/v1/docs` returns HTTP 200 HTML. - [x] The docs HTML contains Swagger UI assets/initialization. - [x] The docs page points at `./openapi.json`. - [x] Existing `GET /api/v1/openapi.json` remains available and parseable. - [x] Tests cover the docs route. - [x] README or template docs mention the API docs URL. - [x] Relevant lint/test checks pass: `make check`, `./scripts/pre-pr.sh`, manual Swagger UI smoke, and Forgejo CI all passed. ### Blocking Issues None. ### Warnings None. ### Verdict Approved for merge.

erik

2026-05-22 10:39:40 -05:00

closed this issue
added
status:done
and removed
status:inprogress
labels

erik commented

2026-05-22 10:39:42 -05:00

Author

Owner

Copy link

Synced from todu comment by @todu on 2026-05-22T15:35:13.459Z

Closing Summary

PR #50 merged: #50

Acceptance criteria evidence:

GET /api/v1/docs returns HTTP 200 HTML: met — Swagger UI route added and tested.
The docs HTML contains Swagger UI assets/initialization: met — test asserts SwaggerUIBundle appears.
The docs page points at ./openapi.json: met — route config and test assert ./openapi.json appears.
Existing GET /api/v1/openapi.json remains available and parseable: met — existing OpenAPI test still passes.
Tests cover the docs route: met — template/site/src/api/__tests__/routes.test.ts covers /api/v1/docs.
README or template docs mention the API docs URL: met — root README and template README mention /api/v1/docs.
Relevant lint/test checks pass: met — make check, ./scripts/pre-pr.sh, PR CI, and main push CI passed.

Readiness: READY

_Synced from todu comment by @todu on 2026-05-22T15:35:13.459Z_ ## Closing Summary PR #50 merged: https://forge.caradoc.com/erik/slugkit/pulls/50 Acceptance criteria evidence: - `GET /api/v1/docs` returns HTTP 200 HTML: met — Swagger UI route added and tested. - The docs HTML contains Swagger UI assets/initialization: met — test asserts `SwaggerUIBundle` appears. - The docs page points at `./openapi.json`: met — route config and test assert `./openapi.json` appears. - Existing `GET /api/v1/openapi.json` remains available and parseable: met — existing OpenAPI test still passes. - Tests cover the docs route: met — `template/site/src/api/__tests__/routes.test.ts` covers `/api/v1/docs`. - README or template docs mention the API docs URL: met — root README and template README mention `/api/v1/docs`. - Relevant lint/test checks pass: met — `make check`, `./scripts/pre-pr.sh`, PR CI, and main push CI passed. Readiness: READY

No Branch/Tag specified

main

release/slug-cli-v0.5.0

release/slug-cli-v0.4.0

release/slug-cli-v0.3.0

release/slug-cli-v0.2.0

release/slug-cli-v0.1.2

release/slug-cli-v0.1.1

feat/task-47be19ea-api-meta-route

feat/task-51eaa27f-swagger-api-docs

feat/task-0dbd25d3-site-config-homepage

feat/task-69937fe4-sqlite-migrations

feat/task-a3cd5595-cli-foundation

feat/task-c272cbda-openapi-health

feat/task-d6397b57-template-foundation

v0.5.0

v0.4.0

v0.3.0

v0.2.0

v0.1.2

v0.1.1

Labels

Clear labels

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

erik/slugkit#49

Reference in a new issue

Repository

erik/slugkit

Title

Body

No description provided.

Delete branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?

Rows
Columns