lidge-jun/codexclaw / plugins/codexclaw/skills/dev-scaffolding
cxc-dev-scaffolding
VerifiedUse for project/module setup and docs. Triggers: scaffold, structure audit, architecture docs, API docs, monorepo setup, 스캐폴딩, 새 프로젝트, 새 기능, 구조 점검, 모듈 추가.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.0 KB |
| agents/openai.yaml | config | 178 B |
| assets/str_func_template.md | markdown | 2.4 KB |
| references/api-docs.md | markdown | 5.5 KB |
| references/external-scaffolding-evidence.md | markdown | 430 B |
| references/implementation-log.md | markdown | 5.5 KB |
| references/monorepo-tooling.md | markdown | 6.9 KB |
| references/scaffold-layout.md | markdown | 8.2 KB |
| references/scaffold-verification.md | markdown | 2.0 KB |
| references/source-of-truth-layout.md | markdown | 6.6 KB |
| scripts/scaffold-audit.shexecutable | script | 5.2 KB |
references/api-docs.md
View on GitHub# API Documentation Generation
## 1. OpenAPI 3.1 Generation
Two approaches — pick one per project and enforce consistently:
| Approach | When to Use | Tools |
|----------|-------------|-------|
| **Code-first** | API already exists, types are the source of truth | `@nestjs/swagger` 8.x, `drf-spectacular` 0.28+, `FastAPI` (built-in), `tsoa` 6.x |
| **Spec-first** | API contract must be agreed before implementation | `openapi-generator-cli` 7.x, Stoplight Studio, Redocly CLI |
```typescript
// Code-first example: NestJS + @nestjs/swagger
@ApiTags('users')
@Controller('users')
export class UsersController {
@Get(':id')
@ApiOperation({ summary: 'Get user by ID' })
@ApiResponse({ status: 200, type: UserDto })
@ApiResponse({ status: 404, description: 'User not found' })
findOne(@Param('id', ParseUUIDPipe) id: string): Promise<UserDto> {
return this.usersService.findOne(id);
}
}
```
```python
# Code-first example: drf-spectacular
@extend_schema(
responses={200: UserSerializer, 404: ErrorSerializer},
tags=["users"],
)
class UserViewSet(viewsets.ModelViewSet):
queryset = User.objects.all()
serializer_class = UserSerializer
```
**Version pinning**: OpenAPI spec version MUST be `3.1.0`. Pin generator CLI versions in `package.json` or CI config — never use `@latest`.
## 2. Developer Portal Structure
```
docs/api/
├── index.html # Redoc or Scalar UI entry
├── openapi.yaml # Generated spec (single source of truth)
├── guides/
│ ├── authentication.md
│ ├── pagination.md
│ ├── error-handling.md
│ └── rate-limiting.md
├── examples/
│ ├── curl/ # Copy-pasteable curl commands
│ └── sdk/ # Language-specific snippets
└── changelog.md # API-level changelog (not app changelog)
```
| Portal Tool | License | Best For |
|-------------|---------|----------|
| **Scalar** 1.x | MIT | Modern UI, try-it-out, OpenAPI 3.1 native |
| **Redoc** 2.x | MIT | Clean reference docs, wide adoption |
| **Stoplight Elements** | Apache-2.0 | Embedded component, design-system friendly |
MUST include: authentication guide, error code table, rate limit documentation, pagination pattern.
## 3. CI Doc Drift Detection
Spec and implementation MUST stay in sync. Detect drift in CI:
The generated spec path below represents a temporary file (e.g.,
`$TMPDIR/fresh-spec.yaml` or `%TEMP%\fresh-spec.yaml`).
```yaml
# GitHub Actions example
- name: Check OpenAPI spec drift
run: |
# Generate fresh spec from code
bun run generate:openapi -- --output "$TMPDIR/fresh-spec.yaml"
# Compare against committed spec
npx oasdiff diff docs/api/openapi.yaml "$TMPDIR/fresh-spec.yaml" \
--fail-on ERR \
--format text
# Check for breaking changes
npx oasdiff breaking docs/api/openapi.yaml "$TMPDIR/fresh-spec.yaml" \
--fail-on ERR
```
| Tool | Purpose | Version |
|------|---------|---------|
| `oasdiff` 1.x | Diff + breaking change detection | Pin in CI |
| `spectral` 6.x | OpenAPI linting rules | Pin in CI |
| `vacuum` 0.14+ | Fast OpenAPI linting (Go, faster than spectral) | Pin in CI |
```bash
# Spectral linting in CI
npx spectral lint docs/api/openapi.yaml --ruleset .spectral.yaml --fail-severity warn
```
Breaking change policy: removing an endpoint, removing a required response field, or changing a field type is a **breaking change** — requires major version bump and 90-day deprecation notice.
## 4. SDK Generation
Generate typed clients from the OpenAPI spec — never hand-write API clients:
| Language | Generator | Output |
|----------|-----------|--------|
| TypeScript | `openapi-typescript` 7.x + `openapi-fetch` 0.13+ | Zero-runtime types + fetch client |
| TypeScript (React Query) | `orval` 7.x | React Query hooks + Zod validation |
| Python | `openapi-python-client` 0.22+ | Pydantic models + httpx client |
| Go | `oapi-codegen` 2.x | Typed structs + chi/echo handlers |
```bash
# openapi-typescript: generate types from spec
npx openapi-typescript docs/api/openapi.yaml -o src/api/schema.d.ts
# orval: generate React Query hooks
npx orval --config orval.config.ts
```
SDK generation runs in CI after spec validation passes. Commit generated files — do not generate at runtime.
## 5. Anti-Patterns
| Banned | Symptom | Fix |
|--------|---------|-----|
| Hand-written API clients | Drift from spec, type mismatches | Generate from OpenAPI spec (§4) |
| Spec committed but never validated in CI | Spec rots silently | Add oasdiff + spectral to CI (§3) |
| `@latest` for generator CLIs | Non-reproducible builds | Pin exact version in package.json / CI |
| API docs on wiki/Notion only | Docs drift from code within days | Co-locate in repo, generate from code/spec |
| Missing error response schemas | Clients cannot handle errors properly | Document every 4xx/5xx with response schema |
## Pre-flight
- [ ] OpenAPI spec is version `3.1.0` and validates with spectral/vacuum
- [ ] CI pipeline includes spec drift detection (oasdiff or equivalent)
- [ ] Breaking change policy is documented and enforced in CI
- [ ] SDK generation is automated from spec, not hand-written
- [ ] Developer portal includes auth guide, error codes, pagination, rate limits
- [ ] Generator CLI versions are pinned (no `@latest`)
## 6. Cross-References
- **API design patterns**: `dev-backend/references/core/api-design.md`
- **API lifecycle & deprecation**: `dev-backend/references/core/api-lifecycle.md` (Wave 1)
- **Health checks**: `dev-backend/references/core/health-checks.md`
- **CI/CD pipeline integration**: `dev-devops` (Wave 2)
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: 467k | 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: 467k | 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: 467k | 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: 193k | Updated | Claude CodeCodex | Verified | Install |