api-artifacts

# API Artifacts Generate ready-to-use API documentation and testing artifacts from the system manifest. These artifacts let developers import specs directly into tools like Swagger UI, Postman, and AsyncAPI Studio. --- ## OpenAPI 3.1 Specification Generate one OpenAPI spec per REST API service in the manifest. ### Structure ```yaml openapi: 3.1.0 info: title: "{{service-name}} API" description: "{{service-description}}" version: "0.1.0" servers: - url: http://localhost:{{port}} description: Local development - url: https://{{service-name}}.{{domain}} description: Production security: - bearerAuth: [] paths: # Generate from service responsibilities + shared types /health: get: summary: Health check operationId: getHealth tags: [system] security: [] responses: "200": description: Service is healthy content: application/json: schema: type: object properties: status: type: string example: "ok" service: type: string example: "{{service-name}}" /{{resource}}: get: summary: "List {{resource}}" operationId: "list{{Resource}}" tags: [{{resource}}] parameters: - name: page in: query schema: type: integer default: 1 - name: limit in: query schema: type: integer default: 20 maximum: 100 responses: "200": description: "List of {{resource}}" content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/{{Resource}}" pagination: $ref: "#/components/schemas/Pagination" "401": $ref: "#/components/responses/Unauthorized" post: summary: "Create {{resource}}" operationId: "create{{Resource}}" tags: [{{resource}}] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/Create{{Resource}}" example: # Derive from shared type fields responses: "201": description: "{{Resource}} created" content: application/json: schema: $ref: "#/components/schemas/{{Resource}}" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" /{{resource}}/{id}: get: summary: "Get {{resource}} by ID" operationId: "get{{Resource}}" tags: [{{resource}}] parameters: - name: id in: path required: true schema: type: string responses: "200": description: "{{Resource}} details" content: application/json: schema: $ref: "#/components/schemas/{{Resource}}" "404": $ref: "#/components/responses/NotFound" put: summary: "Update {{resource}}" operationId: "update{{Resource}}" tags: [{{resource}}] parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/Update{{Resource}}" responses: "200": description: "{{Resource}} updated" content: application/json: schema: $ref: "#/components/schemas/{{Resource}}" delete: summary: "Delete {{resource}}" operationId: "delete{{Resource}}" tags: [{{resource}}] parameters: - name: id in: path required: true schema: type: string responses: "204": description: "{{Resource}} deleted" components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT schemas: # Derive from shared types in manifest {{Resource}}: type: object properties: id: type: string format: uuid # ... fields from shared type createdAt: type: string format: date-time updatedAt: type: string format: date-time required: [id] Create{{Resource}}: type: object properties: # ... writable fields only (exclude id, timestamps) required: [# ... required fields] Update{{Resource}}: type: object properties: # ... writable fields, all optional Pagination: type: object properties: page: type: integer limit: type: integer total: type: integer totalPages: type: integer Error: type: object properties: code: type: string message: type: string details: type: object responses: BadRequest: description: Invalid request content: application/json: schema: $ref: "#/components/schemas/Error" example: code: "VALIDATION_ERROR" message: "Invalid request body" details: {} Unauthorized: description: Authentication required content: application/json: schema: $ref: "#/components/schemas/Error" example: code: "UNAUTHORIZED" message: "Authentication required" NotFound: description: Resource not found content: application/json: schema: $ref: "#/components/schemas/Error" example: code: "NOT_FOUND" message: "Resource not found" ``` ### Generation Rules 1. **Derive paths from service responsibilities** — Each responsibility maps to a resource. `ticket-management` → `/tickets`, `user-management` → `/users`. 2. **Derive schemas from `domain.entities[]`** — Read `domain.entities[]` as the primary source; each entity becomes a component schema. For SDL location: check `solution.sdl.yaml` first; if absent, check `sdl/` directory and read `sdl/README.md` then the relevant module file (typically `sdl/data.yaml`). Fall back to `shared.types[]` in the manifest if `domain.entities[]` is absent in both SDL formats. 3. **Always include standard CRUD** — GET list, GET by ID, POST, PUT, DELETE for each resource unless the service is read-only or write-only. 4. **Always include health endpoint** — Every service gets `/health` with no auth. 5. **Always include standard error responses** — 400, 401, 403, 404, 500 with consistent Error schema. 6. **Use realistic examples** — Generate example values that make sense for the domain (not "string" or "test"). 7. **Include pagination** — All list endpoints use page/limit pagination. 8. **Match auth to manifest** — Use the auth method from the communication section (JWT bearer, API key, etc.). --- ## Postman Collection Generate one Postman collection per REST API service. Use Postman Collection v2.1 format. ### Structure ```json { "info": { "name": "{{service-name}} API", "description": "{{service-description}}", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{auth_token}}", "type": "string" } ] }, "variable": [ { "key": "base_url", "value": "http://localhost:{{port}}" }, { "key": "auth_token", "value": "" } ], "item": [ { "name": "Health", "item": [ { "name": "Health Check", "request": { "method": "GET", "url": "{{base_url}}/health", "auth": { "type": "noauth" } } } ] }, { "name": "{{Resource}}", "item": [ { "name": "List {{resource}}", "request": { "method": "GET", "url": { "raw": "{{base_url}}/{{resource}}?page=1&limit=20", "host": ["{{base_url}}"], "path": ["{{resource}}"], "query": [ { "key": "page", "value": "1" }, { "key": "limit", "value": "20" } ] } } }, { "name": "Get {{resource}} by ID", "request": { "method": "GET", "url": "{{base_url}}/{{resource}}/{{resource_id}}" } }, { "name": "Create {{resource}}", "request": { "method": "POST", "url": "{{base_url}}/{{resource}}", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "// JSON body with example values from shared types" } } }, { "name": "Update {{resource}}", "request": { "method": "PUT", "url": "{{base_url}}/{{resource}}/{{resource_id}}", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "// JSON body with example values" } } }, { "name": "Delete {{resource}}", "request": { "method": "DELETE", "url": "{{base_url}}/{{resource}}/{{resource_id}}" } } ] } ] } ``` ### Generation Rules 1. **One folder per resource** — Group requests by domain resource (Users, Tickets, etc.). 2. **Include example bodies** — POST and PUT requests include realistic JSON bodies derived from shared types. 3. **Use collection variables** — `base_url` and `auth_token` as variables so the user can switch environments. 4. **Include auth setup** — Collection-level bearer auth with `auth_token` variable. 5. **Order requests logically** — List → Get → Create → Update → Delete within each folder. 6. **Add descriptions** — Each request gets a one-line description of what it does. --- ## AsyncAPI 2.6 Specification Generate one AsyncAPI spec for event-driven / message queue connections in the manifest. ### Structure ```yaml asyncapi: 2.6.0 info: title: "{{project-name}} Events" version: "0.1.0" description: "Event channels for {{project-name}} architecture" servers: development: url: localhost:6379 protocol: redis description: Local Redis for BullMQ production: url: "{{redis-url}}" protocol: redis description: Production Redis channels: {{queue-name}}: description: "{{queue-description}}" publish: operationId: "publish{{EventName}}" summary: "{{event-summary}}" message: $ref: "#/components/messages/{{EventName}}" subscribe: operationId: "consume{{EventName}}" summary: "{{consumer-summary}}" message: $ref: "#/components/messages/{{EventName}}" components: messages: {{EventName}}: name: {{EventName}}