| name | specx-add-delivery-controller |
| description | Add delivery controllers for specx services, especially FastAPI HTTP routes. Use when creating top-level `delivery/` request/response schemas, one controller per scoped use-case set, route registration, FastAPI lifecycle managers, HTTP error translation, delivery-only auth/rate-limit/request services, or integration tests that exercise the delivery edge. |
specx Add Delivery Controller
Use this skill at the framework boundary. Read references/controller.md
before adding controller code.
Workflow
- Put controllers under
delivery/fastapi/controllers/<scope>.py.
- Put request and response schemas under
delivery/fastapi/schemas/.
- Use one controller per scoped set of use cases, for example
TasksController for create/get/list task routes.
- Put controller-only helpers such as auth dependencies, rate limiters, and
request-context readers under
delivery/fastapi/services/.
- Make controllers inherit
BaseController, schemas inherit
BaseFastAPISchema, delivery helpers inherit BaseDeliveryService, and
FastAPI lifespan managers inherit BaseLifecycle[FastAPI].
- Add docstrings with scope and a concrete
Example: to controllers, schemas,
and delivery services.
- Inject use cases or delivery services with
Injected[...]. A simple
delivery-owned /healthz response needs no core workflow; inject
core/health use cases when readiness checks a required external dependency
or probe policy is reused across deliveries.
- Map request schema/path data into the use case's same-file
Command or
Query input.
- Call the use case.
- Map the result into a response schema.
- Declare the success status explicitly when it is not
200, such as 201
for a resource-creating POST or 204 for a response with no body.
- Translate known application exceptions into stable, non-sensitive HTTP
responses. Do not expose raw exception messages.
- Register full public business route paths such as
/api/v1/users. Do not
split API prefixes across routers and route fragments. Operational probes
are the only unversioned exception: /healthz and /readyz.
- For FastAPI apps with long-lived resources, inject
FastAPILifecycle into
the app factory and pass it to FastAPI(lifespan=...).
- Add integration tests at the HTTP boundary, including the declared success
code and each translated application error.
Code Style
Use blank lines as logical separators in all code. Keep related statements
together, but separate independent setup, action, assertion, response, branch,
and transformation groups so long blocks stay readable.
References
references/controller.md - FastAPI controller class pattern, app factory
registration, schemas, and tests.
