erik/slugkit
1
0
Fork 0
Code Issues 6 Pull requests Projects Releases 6 Packages Wiki Activity Actions

Add OpenAPI foundation and health API #34

New issue
Closed
opened 2026-05-19 19:51:45 -05:00 by erik · 3 comments
erik commented 2026-05-19 19:51:45 -05:00
Owner
Copy link

Goal

Establish the Slugkit API v1 foundation, OpenAPI source of truth, shared error shapes, auth conventions, and API health route.

Spec: docs/specs/00-openapi-foundation-health.md

Requirements

  • Add the /api/v1 API surface to the template website.
  • Define OpenAPI as the API source of truth and expose the OpenAPI document at the documented location.
  • Add the API health route from the spec.
  • Add shared response wrappers, validation error shape, not-found error shape, authentication error shape, and standardized 501 Not Implemented shape.
  • Add shared bearer-auth middleware scaffolding for protected API routes.
  • Add tests that validate route behavior and the OpenAPI document is reachable and parseable.
  • Keep public website routes separate from /api/v1 management routes.

Acceptance criteria

  • /api/v1/health returns the documented success JSON.
  • The OpenAPI document is exposed at the documented URL and is valid JSON.
  • Shared API success and error response shapes are implemented.
  • Standardized 501 Not Implemented response shape is available for unsupported routes/features.
  • Protected route middleware rejects missing/invalid bearer credentials once auth is wired.
  • Tests cover API health, OpenAPI document availability, and shared error shape helpers.
  • Relevant lint/test checks pass.

Dependencies

  • task-d6397b57
## Goal Establish the Slugkit API v1 foundation, OpenAPI source of truth, shared error shapes, auth conventions, and API health route. Spec: `docs/specs/00-openapi-foundation-health.md` ## Requirements - Add the `/api/v1` API surface to the template website. - Define OpenAPI as the API source of truth and expose the OpenAPI document at the documented location. - Add the API health route from the spec. - Add shared response wrappers, validation error shape, not-found error shape, authentication error shape, and standardized `501 Not Implemented` shape. - Add shared bearer-auth middleware scaffolding for protected API routes. - Add tests that validate route behavior and the OpenAPI document is reachable and parseable. - Keep public website routes separate from `/api/v1` management routes. ## Acceptance criteria - [ ] `/api/v1/health` returns the documented success JSON. - [ ] The OpenAPI document is exposed at the documented URL and is valid JSON. - [ ] Shared API success and error response shapes are implemented. - [ ] Standardized `501 Not Implemented` response shape is available for unsupported routes/features. - [ ] Protected route middleware rejects missing/invalid bearer credentials once auth is wired. - [ ] Tests cover API health, OpenAPI document availability, and shared error shape helpers. - [ ] Relevant lint/test checks pass. ## Dependencies - task-d6397b57
erik commented 2026-05-19 22:14:09 -05:00
Author
Owner
Copy link

Synced from todu comment by @todu on 2026-05-20T03:12:14.896Z

PR Review: Approved

PR: #40

Summary

Reviewed the OpenAPI foundation PR against the task acceptance criteria. The PR adds the Slugkit API v1 foundation under /api/v1, exposes the OpenAPI 3.1 document, implements the API health route, adds shared API response helpers, adds a bearer-auth middleware scaffold, and covers the new behavior with tests.

Acceptance Criteria

  • /api/v1/health returns the documented success JSON.
  • The OpenAPI document is exposed at the documented URL and is valid JSON.
  • Shared API success and error response shapes are implemented.
  • Standardized 501 Not Implemented response shape is available for unsupported routes/features.
  • Protected route middleware rejects missing/invalid bearer credentials once auth is wired.
  • Tests cover API health, OpenAPI document availability, and shared error shape helpers.
  • Relevant lint/test checks pass: ./scripts/pre-pr.sh and Forgejo CI succeeded.

Blocking Issues

None.

Warnings

None.

Verdict

Approved for merge.

_Synced from todu comment by @todu on 2026-05-20T03:12:14.896Z_ ## PR Review: Approved PR: https://forge.caradoc.com/erik/slugkit/pulls/40 ### Summary Reviewed the OpenAPI foundation PR against the task acceptance criteria. The PR adds the Slugkit API v1 foundation under `/api/v1`, exposes the OpenAPI 3.1 document, implements the API health route, adds shared API response helpers, adds a bearer-auth middleware scaffold, and covers the new behavior with tests. ### Acceptance Criteria - [x] `/api/v1/health` returns the documented success JSON. - [x] The OpenAPI document is exposed at the documented URL and is valid JSON. - [x] Shared API success and error response shapes are implemented. - [x] Standardized `501 Not Implemented` response shape is available for unsupported routes/features. - [x] Protected route middleware rejects missing/invalid bearer credentials once auth is wired. - [x] Tests cover API health, OpenAPI document availability, and shared error shape helpers. - [x] Relevant lint/test checks pass: `./scripts/pre-pr.sh` and Forgejo CI succeeded. ### Blocking Issues None. ### Warnings None. ### Verdict Approved for merge.
erik commented 2026-05-19 22:24:42 -05:00
Author
Owner
Copy link

Synced from todu comment by @todu on 2026-05-20T03:21:04.973Z

PR Review: Approved

PR: #40

Summary

Reviewed latest PR state at commit 33d1677. The PR adds the Slugkit API v1 foundation under /api/v1, exposes /api/v1/openapi.json, implements /api/v1/health, adds shared response/error helpers, adds bearer-auth middleware scaffolding, keeps public website routes separate, and switches the dev server to tsx watch so code changes reload automatically.

Acceptance Criteria

  • /api/v1/health returns the documented success JSON.
  • The OpenAPI document is exposed at the documented URL and is valid JSON.
  • Shared API success and error response shapes are implemented.
  • Standardized 501 Not Implemented response shape is available for unsupported routes/features.
  • Protected route middleware rejects missing/invalid bearer credentials once auth is wired.
  • Tests cover API health, OpenAPI document availability, shared error shape helpers, and bearer-auth middleware behavior.
  • Relevant lint/test checks pass: Forgejo CI succeeded on the latest commit; local make check passed after the dev-watch change.

Blocking Issues

None.

Warnings

None.

Verdict

Approved for merge.

_Synced from todu comment by @todu on 2026-05-20T03:21:04.973Z_ ## PR Review: Approved PR: https://forge.caradoc.com/erik/slugkit/pulls/40 ### Summary Reviewed latest PR state at commit `33d1677`. The PR adds the Slugkit API v1 foundation under `/api/v1`, exposes `/api/v1/openapi.json`, implements `/api/v1/health`, adds shared response/error helpers, adds bearer-auth middleware scaffolding, keeps public website routes separate, and switches the dev server to `tsx watch` so code changes reload automatically. ### Acceptance Criteria - [x] `/api/v1/health` returns the documented success JSON. - [x] The OpenAPI document is exposed at the documented URL and is valid JSON. - [x] Shared API success and error response shapes are implemented. - [x] Standardized `501 Not Implemented` response shape is available for unsupported routes/features. - [x] Protected route middleware rejects missing/invalid bearer credentials once auth is wired. - [x] Tests cover API health, OpenAPI document availability, shared error shape helpers, and bearer-auth middleware behavior. - [x] Relevant lint/test checks pass: Forgejo CI succeeded on the latest commit; local `make check` passed after the dev-watch change. ### Blocking Issues None. ### Warnings None. ### Verdict Approved for merge.
erik 2026-05-19 22:29:55 -05:00
erik commented 2026-05-19 22:29:57 -05:00
Author
Owner
Copy link

Synced from todu comment by @todu on 2026-05-20T03:27:42.065Z

Closing Summary

PR #40 merged: #40

Acceptance criteria evidence:

  • /api/v1/health returns the documented success JSON: met — implemented under template/site/src/api/routes/health.ts, covered by tests, manually verified, and confirmed by user testing.
  • The OpenAPI document is exposed at the documented URL and is valid JSON: met — /api/v1/openapi.json implemented and tested as parseable JSON with OpenAPI 3.1 metadata.
  • Shared API success and error response shapes are implemented: met — template/site/src/api/responses.ts includes success, validation, not-found, authentication, and not-implemented helpers with tests.
  • Standardized 501 Not Implemented response shape is available for unsupported routes/features: met — createNotImplementedErrorResponse returns the standardized NOT_IMPLEMENTED shape and is included in OpenAPI schemas.
  • Protected route middleware rejects missing/invalid bearer credentials once auth is wired: met — createBearerAuthMiddleware rejects missing/invalid bearer tokens with 401, covered by tests.
  • Tests cover API health, OpenAPI document availability, and shared error shape helpers: met — API route, response helper, and bearer-auth tests pass.
  • Relevant lint/test checks pass: met — ./scripts/pre-pr.sh, PR CI, and main push CI passed.

Readiness: READY

_Synced from todu comment by @todu on 2026-05-20T03:27:42.065Z_ ## Closing Summary PR #40 merged: https://forge.caradoc.com/erik/slugkit/pulls/40 Acceptance criteria evidence: - `/api/v1/health` returns the documented success JSON: met — implemented under `template/site/src/api/routes/health.ts`, covered by tests, manually verified, and confirmed by user testing. - The OpenAPI document is exposed at the documented URL and is valid JSON: met — `/api/v1/openapi.json` implemented and tested as parseable JSON with OpenAPI 3.1 metadata. - Shared API success and error response shapes are implemented: met — `template/site/src/api/responses.ts` includes success, validation, not-found, authentication, and not-implemented helpers with tests. - Standardized `501 Not Implemented` response shape is available for unsupported routes/features: met — `createNotImplementedErrorResponse` returns the standardized `NOT_IMPLEMENTED` shape and is included in OpenAPI schemas. - Protected route middleware rejects missing/invalid bearer credentials once auth is wired: met — `createBearerAuthMiddleware` rejects missing/invalid bearer tokens with `401`, covered by tests. - Tests cover API health, OpenAPI document availability, and shared error shape helpers: met — API route, response helper, and bearer-auth tests pass. - Relevant lint/test checks pass: met — `./scripts/pre-pr.sh`, PR CI, and main push CI passed. Readiness: READY
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
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   
activitypub

   
admin

   
api

   
articles

   
auth

   
bug

   
cleanup

   
cli

   
comments

   
compatibility

   
config

   
contacts

   
database

   
deployment

   
design

   
dev-env

   
docs

   
documentation

   
email

   
enhancement

   
feature

   
federation

   
feed

   
homepage

   
implementation

   
integration

   
media

   
openapi

   
priority:high

   
priority:low

   
priority:medium

   
proof

   
public-routes

   
public-ui

   
release

   
safety

   
social

   
sources

   
status:active

   
status:canceled

   
status:done

   
status:inprogress

   
status:waiting

   
syndication

   
tailwind

   
template

   
test

   
web
No labels
activitypub
admin
api
articles
auth
bug
cleanup
cli
comments
compatibility
config
contacts
database
deployment
design
dev-env
docs
documentation
email
enhancement
feature
federation
feed
homepage
implementation
integration
media
openapi
priority:high
priority:low
priority:medium
proof
public-routes
public-ui
release
safety
social
sources
status:active
status:canceled
status:done
status:inprogress
status:waiting
syndication
tailwind
template
test
web
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#34
No description provided.