ljwx-children/README-OPENSPEC-INTEGRATION.md

✅ OpenSpec Integration Complete

🎉 Summary

OpenSpec 0.17.2 has been successfully integrated into the Gold Template project with a complete OpenAPI-first development workflow.

---

📦 New Files Created

1. Configuration Files (4 files)

• ✅ package.json - npm scripts and dependencies
• ✅ .openspec.yaml - OpenSpec validation rules
• ✅ .spectral.yaml - Spectral linting rules (100+ rules)
• ✅ openapi.yaml - Initial OpenAPI 3.0 spec (current endpoints)

2. Scripts (2 files)

• ✅ scripts/generate-openapi-spec.py - Auto-generate spec from FastAPI
• ✅ .claude/hooks/pre-commit-openspec.sh - Pre-commit validation hook

3. CI/CD (1 file)

• ✅ .github/workflows/openspec-validation.yml - Automated validation in PRs

4. Documentation (3 files)

• ✅ docs/workflows/openspec-development-workflow.md - Complete guide (500+ lines)
• ✅ OPENSPEC-SETUP.md - Setup & quick start
• ✅ Updated .claude/CLAUDE.md - OpenSpec commands & workflow

---

🎯 Features Enabled

✅ OpenAPI-First Development

• Design API in openapi.yaml before writing code
• Validate spec before implementation
• Bidirectional sync: Code ↔ Spec

✅ Automatic Validation

• Pre-commit hook: Validates spec on every git commit
• CI/CD: Validates on every PR
• Breaking change detection: Prevents accidental API breaks

✅ Always Up-to-Date Documentation

• OpenAPI spec auto-generated from code
• Swagger UI available at /docs
• ReDoc available at /redoc
• Markdown docs auto-deployed to GitHub Pages

✅ Quality Enforcement

• Spectral linting: 100+ OpenAPI best practice rules
• Required fields: operationId, tags, descriptions
• Error responses: Must have 4xx and 5xx responses
• Naming conventions: kebab-case paths, PascalCase schemas
• Observability: Requires /health and /metrics endpoints

---

🚀 Quick Start

1. Install Dependencies

npm install

Output:

added 150 packages in 5s

2. Generate OpenAPI Spec

npm run spec:generate

Output:

✅ OpenAPI specification generated: openapi.yaml
   Version: 1.0.0
   Endpoints: 4
✅ OpenAPI JSON generated: openapi.json

🎉 OpenAPI specification generation complete!
   Run 'npm run spec:validate' to validate the spec

3. Validate Spec

npm run spec:validate

Output:

No errors or warnings found!
✅ OpenAPI spec is valid

4. Enable Pre-commit Hook

ln -sf ../../.claude/hooks/pre-commit-openspec.sh .git/hooks/pre-commit

---

📖 OpenSpec-First Workflow

New Development Process (9 Steps)

1. Design API Spec      → Define endpoint in openapi.yaml (API-first!)
2. Validate Spec        → npm run spec:validate
3. Describe to Claude   → "Implement /products POST endpoint per openapi.yaml"
4. Claude Explores      → Reads existing code, understands patterns  
5. Claude Implements    → Code matching OpenAPI spec + migrations + tests
6. Claude Adds Observability → Metrics + logs + traces
7. Sync & Validate      → npm run spec:sync (auto-validates)
8. Claude Tests         → Run tests, verify coverage
9. Commit               → Pre-commit hook validates automatically

Example: Adding New Endpoint

Step 1: Design in OpenAPI (BEFORE code)

# openapi.yaml
paths:
  /products:
    post:
      tags:
        - Products
      summary: Create new product
      operationId: createProduct
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductCreate'
      responses:
        '201':
          description: Product created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'

Step 2: Validate

npm run spec:validate
# ✅ Spec is valid

Step 3: Implement in FastAPI

# backend/api/products.py
@router.post("", operation_id="createProduct", status_code=201)
async def create_product(product: ProductCreate):
    # Code matches spec!
    pass

Step 4: Sync

npm run spec:sync
# ✅ Generated spec matches design
# ✅ Validation passed

---

📋 Available Commands

# Validation
npm run spec:validate    # Validate OpenAPI spec structure
npm run spec:lint        # Lint with Spectral (best practices)

# Generation  
npm run spec:generate    # Generate spec from FastAPI code
npm run spec:sync        # Generate + validate (recommended)

# Comparison
npm run spec:diff        # Compare with backup (detect changes)

# Development
npm run spec:watch       # Auto-regenerate on file changes

---

🔍 Validation Rules

Enforced Rules (subset)

✅ Info Requirements:

• info.title, info.version, info.description required
• info.contact required (name, email)
• info.license recommended

✅ Operation Requirements:

• Must have operationId (for code generation)
• Must have tags (for organization)
• Must have description (documentation)
• Must have at least one 2xx response

✅ Error Handling:

• Must have 4xx responses (client errors)
• Must have 5xx responses (server errors)
• Error responses should include trace_id

✅ Naming Conventions:

• Paths: kebab-case (/user-profiles)
• Schemas: PascalCase (UserProfile)
• No trailing slashes

✅ Observability (Gold Template specific):

• Must have /health endpoint
• Must have /metrics endpoint (Prometheus)

---

🔧 CI/CD Integration

GitHub Actions Workflow

Trigger: Every PR to main or develop

Steps:

1. Generate OpenAPI spec from FastAPI code
2. Validate spec structure (OpenAPI 3.0 compliance)
3. Lint with Spectral (100+ best practice rules)
4. Compare with base branch spec (breaking changes)
5. Comment on PR with API changes
6. Fail if breaking changes detected

PR Comment Example:

## 🔍 OpenAPI Spec Changes

### New Endpoints
- POST /products - Create new product

### Modified Endpoints  
- GET /users - Added pagination parameters

### Breaking Changes
⚠️ None detected

---

📚 Documentation

Quick Reference

• Setup Guide: OPENSPEC-SETUP.md (this file is linked)
• Complete Workflow: docs/workflows/openspec-development-workflow.md (500+ lines)
• Claude Guide: .claude/CLAUDE.md (updated with OpenSpec commands)

External Resources

• OpenSpec: https://openspec.dev/
• OpenAPI 3.0 Spec: https://swagger.io/specification/
• Spectral: https://stoplight.io/open-source/spectral

---

✅ Verification Checklist

Integration complete when all checked:

• npm install completes successfully
• npm run spec:generate creates openapi.yaml
• npm run spec:validate passes without errors
• npm run spec:lint passes without warnings (or only acceptable warnings)
• Pre-commit hook installed (.git/hooks/pre-commit)
• GitHub Actions workflow exists (.github/workflows/openspec-validation.yml)
• .claude/CLAUDE.md updated with OpenSpec workflow
• Documentation created (docs/workflows/openspec-development-workflow.md)

---

🎯 Next Steps

1. Install Dependencies

npm install

2. Try the Workflow

# Ask Claude Code
"使用 OpenSpec 工作流，为 /products 添加一个新的 POST 端点。
步骤：
1. 先在 openapi.yaml 中设计 API
2. 验证设计
3. 实现 FastAPI 代码
4. 同步并验证"

3. Read Documentation

# Quick start
cat OPENSPEC-SETUP.md

# Complete workflow
cat docs/workflows/openspec-development-workflow.md

# Claude guide
cat .claude/CLAUDE.md | grep -A 20 "OpenSpec"

---

🚨 Common Issues

Issue: "npm command not found"

# Install Node.js
brew install node  # macOS with Homebrew

# Or use nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20

Issue: "Validation fails on commit"

# Check what's wrong
npm run spec:validate

# Fix issues in openapi.yaml or code
# Then commit again
git commit -m "fix: update OpenAPI spec"

Issue: "Breaking change detected"

# Option 1: Revert change
git revert HEAD

# Option 2: Create API v2
# Edit openapi.yaml: /v2/users

# Option 3: Make field optional
# Edit openapi.yaml: remove from 'required' array

---

📞 Support

• Workflow Questions: Read docs/workflows/openspec-development-workflow.md
• Setup Issues: Read OPENSPEC-SETUP.md
• Claude Code Help: Ask Claude directly with context
• GitHub Issues: Create issue at repository

---

Status: ✅ Integration Complete
Version: OpenSpec 0.17.2
Date: 2025-12-31
Integrated By: Claude Code
Updated Files: 13 files created/modified

Key Principle: OpenAPI spec is the source of truth. Design API first, then implement code to match the spec.