SpillwaveSolutions/document-specialist-skill / skills/documentation-specialist
documentation-specialist
VerifiedThis skill should be used when creating professional software documentation (SRS, PRD, OpenAPI, SDD, architecture docs, user manuals, tutorials, runbooks) from templates (greenfield) or reverse-engineering documentation from existing code like Spring Boot or FastAPI (brownfield). Also handles documentation audits/reviews, format conversion (Markdown, DOCX, PDF), and diagram generation (Mermaid first: C4, sequence, class, ER, state, flowchart; PlantUML Salt for UI wireframes and leftover UML). Use when asked to "create documentation", "document my code", "write SRS", "generate PRD", "write DESIGN_DOC.md", "architecture document", "wireframe", or "documentation specialist".
references/workflows/greenfield/openapi-guide.md
View on GitHub# OpenAPI Generation Guide
---
TOKEN_BUDGET: 250
TIER: 3
LOAD_TRIGGER: CREATE_NEW + OpenAPI/API spec
DEPENDENCIES: greenfield-workflow.md
---
## OpenAPI 3.0 Structure
### 1. Info Section
```yaml
openapi: "3.0.3"
info:
title: "[API Name]"
description: "[Purpose and overview]"
version: "1.0.0"
contact:
name: API Support
email: api@example.com
```
### 2. Servers
```yaml
servers:
- url: https://api.example.com/v1
description: Production
- url: https://staging-api.example.com/v1
description: Staging
```
### 3. Tags (Logical Grouping)
```yaml
tags:
- name: Users
description: User management operations
- name: Authentication
description: Auth and authorization
```
### 4. Components (Reusable)
**Security Schemes**:
```yaml
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
```
**Schemas** (Data Models):
```yaml
schemas:
User:
type: object
required: [id, email]
properties:
id:
type: string
format: uuid
email:
type: string
format: email
```
**Common Responses**:
```yaml
responses:
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
```
### 5. Paths (Endpoints)
```yaml
paths:
/users/{id}:
get:
tags: [Users]
summary: Get user by ID
operationId: getUserById
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'404':
$ref: '#/components/responses/NotFound'
security:
- BearerAuth: []
```
## Best Practices
1. **Use $ref** for reusable components
2. **Include examples** for request/response bodies
3. **Document all response codes** (200, 400, 401, 404, 500)
4. **Add descriptions** to all fields
5. **Use semantic operationIds** (getUserById, createUser)
## Reference
For API documentation standards: [05-api-openapi.md](../../reference/05-api-openapi.md)
For Stripe-style best practices: [05-api-stripe-gold-standard.md](../../reference/05-api-stripe-gold-standard.md)
For complete example: [task-api-openapi.yaml](../../examples/greenfield/task-api-openapi.yaml)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |