digiqagent 1.2.0

package/skills/swagger-generator/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: swagger-generator
+description: Use when generating or updating OpenAPI/Swagger specs from codebase routes, controllers, models, or from an API design document
+---
+
+# Swagger / OpenAPI Specification Generator
+
+## Overview
+
+Produce a complete, valid OpenAPI 3.0 specification from the project's source code **or** a provided API design document. The output is a ready-to-use `openapi.yaml` (or `swagger.yaml`) file.
+
+**Core principle:** Every endpoint, every parameter, every response code — documented. If it exists in code, it exists in the spec.
+
+## When to Use
+
+- New API project needs documentation
+- Existing API has no spec or an outdated spec
+- API design document needs to be formalized into OpenAPI
+- Before generating Postman collections (prerequisite for `digiqagent:postman-collection-generator`)
+
+## Input Detection
+
+Determine the source **before** starting generation:
+
+### Source A — Codebase Analysis
+
+Scan the project to detect the framework:
+
+| Framework | Look For |
+|-----------|----------|
+| **Express** | `app.get/post/put/delete`, `router.*`, route files |
+| **NestJS** | `@Controller`, `@Get/@Post/@Put/@Delete` decorators |
+| **FastAPI** | `@app.get/post`, `@router.*`, Pydantic models |
+| **Spring Boot** | `@RestController`, `@RequestMapping`, `@GetMapping` |
+| **Django REST** | `ViewSet`, `@api_view`, `urlpatterns` |
+| **Go (Gin/Echo)** | `r.GET/POST`, `e.GET/POST`, handler functions |
+| **Rails** | `routes.rb`, `resources :`, controller actions |
+
+**Scanning order:**
+1. Route/controller files (endpoints, methods, URL patterns)
+2. DTOs / models / types / interfaces (request/response schemas)
+3. Middleware (auth schemes, rate limiting, CORS)
+4. Validation logic (required fields, constraints, formats)
+5. Error handling (error response shapes, status codes)
+
+### Source B — Spec / Requirements Document
+
+If a design document, requirements doc, or API description is provided:
+1. Extract each endpoint (method + path)
+2. Identify request parameters, bodies, and response shapes from descriptions
+3. Infer validation rules and constraints from requirements language
+4. Map described auth mechanisms to OpenAPI securitySchemes
+
+### Mixed Source
+
+When both are available, **codebase is truth, spec fills gaps**. Flag discrepancies between the two.
+
+## Generation Process
+
+### Step 1 — Discover Endpoints
+
+For each endpoint, capture:
+- HTTP method
+- URL path (with path parameters identified)
+- Handler function / controller method name
+- Associated middleware (auth, validation)
+
+```
+GET    /api/users          → listUsers
+POST   /api/users          → createUser
+GET    /api/users/:id      → getUser
+PUT    /api/users/:id      → updateUser
+DELETE /api/users/:id      → deleteUser
+```
+
+### Step 2 — Extract Schemas
+
+For each endpoint, extract:
+- **Path parameters** — name, type, required (always true for path params)
+- **Query parameters** — name, type, required/optional, defaults, enums
+- **Request body** — content type, schema (from DTO/model/interface)
+- **Response body** — per status code, content type, schema
+- **Headers** — custom required headers
+
+Map language types to OpenAPI types:
+
+| Source Type | OpenAPI Type | Format |
+|-------------|-------------|--------|
+| `string` | `string` | — |
+| `number`, `float`, `double` | `number` | `float` / `double` |
+| `int`, `integer` | `integer` | `int32` / `int64` |
+| `boolean`, `bool` | `boolean` | — |
+| `Date`, `datetime` | `string` | `date-time` |
+| `UUID`, `uuid` | `string` | `uuid` |
+| `email` (validated) | `string` | `email` |
+| Array of T | `array` | items: T |
+| Object / interface | `object` | properties from fields |
+
+### Step 3 — Build OpenAPI Structure
+
+Assemble the spec following this skeleton:
+
+```yaml
+openapi: 3.0.3
+info:
+  title: <Project Name> API
+  description: <from README or package description>
+  version: <from package version or "1.0.0">
+  contact:
+    name: <from package author>
+
+servers:
+  - url: http://localhost:<port>
+    description: Local development
+  - url: https://api.<domain>
+    description: Production
+
+paths:
+  /api/resource:
+    get:
+      tags: [Resource]
+      summary: List resources
+      operationId: listResources
+      parameters: [...]
+      responses:
+        '200': { description: Success, content: ... }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '500': { $ref: '#/components/responses/InternalError' }
+
+components:
+  schemas: { ... }
+  responses:
+    BadRequest: { ... }
+    Unauthorized: { ... }
+    Forbidden: { ... }
+    NotFound: { ... }
+    InternalError: { ... }
+  securitySchemes: { ... }
+
+security:
+  - bearerAuth: []
+```
+
+### Step 4 — Include All Details
+
+**For EVERY endpoint, include these response codes at minimum:**
+
+| Method | Success | Common Errors |
+|--------|---------|---------------|
+| GET (list) | 200 | 400, 401, 403, 500 |
+| GET (single) | 200 | 400, 401, 403, 404, 500 |
+| POST (create) | 201 | 400, 401, 403, 409, 422, 500 |
+| PUT/PATCH | 200 | 400, 401, 403, 404, 422, 500 |
+| DELETE | 200 or 204 | 400, 401, 403, 404, 500 |
+
+**For request bodies:**
+- Mark required fields explicitly
+- Include `example` values with realistic data
+- Add `minLength`, `maxLength`, `minimum`, `maximum`, `pattern` where validation exists
+
+**For parameters:**
+- Include `description` for every parameter
+- Mark `required: true/false` explicitly
+- Add `enum` values where applicable
+
+### Step 5 — Write File
+
+Output the complete spec as:
+- **Default:** `openapi.yaml` at the project root
+- **User override:** write to the path specified by the developer
+- **Format:** YAML preferred (more readable), JSON if requested
+
+### Step 6 — Verify
+
+Before claiming the spec is complete:
+
+1. **Structural check** — every path has at least one operation, every operation has at least one response
+2. **Schema completeness** — all `$ref` references resolve to defined components
+3. **Consistency** — operationIds are unique, tag names are consistent, naming follows convention (camelCase for operationId, PascalCase for schemas)
+4. **Error responses** — every mutating endpoint has 400/401/500 responses
+5. **Examples** — every schema has an `example` or individual field examples
+6. Apply `digiqagent:verification-before-completion` — evidence before claims
+
+## Red Flags — STOP and Fix
+
+| Problem | Fix |
+|---------|-----|
+| Endpoint in code but not in spec | Add it. No undocumented endpoints. |
+| Response code missing | Add all relevant codes per the table above. |
+| Schema has no `example` | Add realistic example data. |
+| `$ref` points to undefined schema | Define the schema or fix the reference. |
+| No `securitySchemes` but auth middleware exists | Define the scheme (bearer, apiKey, oauth2). |
+| Path parameter not in `parameters` | Add it with `in: path, required: true`. |
+| `operationId` missing or duplicated | Every operation needs a unique operationId. |
+| Inconsistent naming | Pick a convention and apply it everywhere. |
+| No error response schemas | Define standard error response in components. |
+
+## Common Patterns
+
+See @openapi-patterns.md for reusable patterns:
+- Standard error response schema
+- Pagination (offset/limit and cursor-based)
+- Authentication schemes
+- File upload/download
+- Common headers
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| operationId | camelCase, verb + noun | `listUsers`, `createOrder` |
+| Schema name | PascalCase | `User`, `CreateUserRequest` |
+| Path | kebab-case, plural nouns | `/api/user-profiles` |
+| Tags | PascalCase, plural | `Users`, `OrderItems` |
+| Query params | camelCase | `pageSize`, `sortBy` |
+
+## Verification Checklist
+
+Before marking generation complete:
+
+- [ ] Every route/controller endpoint has a corresponding path in the spec
+- [ ] Every path operation has an operationId
+- [ ] Every path operation has at least success + error responses
+- [ ] Every request body schema marks required fields
+- [ ] Every schema includes example values
+- [ ] All `$ref` references resolve
+- [ ] Security schemes match actual auth implementation
+- [ ] Servers list includes at least local dev URL
+- [ ] Info section has title, description, version
+- [ ] File written and path confirmed to user
+
+Can't check all boxes? Fix the spec. Don't ship incomplete documentation.
+
+## Next Steps
+
+After generating the OpenAPI spec:
+1. Use `digiqagent:postman-collection-generator` to produce a Postman collection from the spec
+2. Use `digiqagent:postman-test-suite-generator` to add positive/negative test scenarios