OpenSpec 使用指南

概述

OpenSpec 是一个用于处理 OpenAPI 规范的工具套件，提供 CLI 命令来创建、验证、生成和维护 API 文档。

OpenSpec Init 作用

主要功能

创建初始模板
生成标准的 OpenAPI/Swagger 规范文件
提供预定义的项目结构和基础配置
项目脚手架 bash openspec init my-api 创建的项目结构： my-api/ ├── openapi.yaml # 主要的 API 规范文件 ├── package.json # 项目配置 └── README.md # 项目文档
规范标准化
确保生成的 API 规范符合 OpenAPI 标准
包含必要的字段和结构（info、paths、components 等）
快速启动开发
减少手动创建规范文件的时间
避免格式错误和遗漏

使用场景

开始新的 API 项目
为现有 API 创建规范文档
团队统一 API 开发规范
集成到 CI/CD 流程中

OpenSpec 主要功能

核心功能模块

1. 规范管理

初始化项目：openspec init
验证规范：openspec validate
规范转换：YAML ↔ JSON 格式转换

2. 代码生成

# 生成客户端代码
openspec generate client --language typescript

# 生成服务器端代码
openspec generate server --language nodejs

# 生成 API 文档
openspec generate docs

3. 文档相关

静态文档生成：HTML、Markdown 等格式
实时预览：本地服务器实时查看
文档导出：多格式导出支持

4. Mock 服务

# 启动 Mock 服务器
openspec mock --port 3000

根据 OpenAPI 规范模拟 API 响应
用于前端开发测试

工作流程示例

开发阶段

# 1. 初始化项目
openspec init my-project

# 2. 编辑 openapi.yaml
# 3. 验证规范
openspec validate openapi.yaml

# 4. 启动 Mock 服务测试
openspec mock openapi.yaml

生产阶段

# 生成客户端 SDK
openspec generate client --language javascript

# 生成 API 文档网站
openspec generate docs --output ./docs

主要优势

标准化：统一 API 开发规范
效率提升：自动化生成代码和文档
一致性：保持设计、文档、实现一致
协作友好：便于团队协同开发

文档维护流程

1. 初始化文档项目

# 创建新的 API 文档项目
openspec init my-api-docs
cd my-api-docs

# 或为现有项目初始化
openspec init --existing

2. 实时文档预览

# 启动实时预览服务器
openspec serve openapi.yaml --port 3000

# watch 模式，文件更改自动刷新
openspec serve openapi.yaml --watch

3. 规范验证

# 检查 OpenAPI 规范正确性
openspec validate openapi.yaml

# 严格模式验证
openspec validate openapi.yaml --strict

4. 文档生成与导出

# 生成 HTML 文档
openspec generate docs openapi.yaml --output ./dist

# 生成多格式文档
openspec generate docs openapi.yaml --format html,md,json

# 自定义主题
openspec generate docs openapi.yaml --theme redoc

5. 版本化文档管理

# 为不同版本生成文档
openspec generate docs openapi.v1.yaml --output ./docs/v1
openspec generate docs openapi.v2.yaml --output ./docs/v2

6. API 更新维护

# openapi.yaml - 维护变更历史
info:
  title: User API
  version: 1.2.0
  description: |
    # 变更日志

    ## v1.2.0 (2024-01-15)
    - 新增用户头像上传接口
    - 修复分页参数验证问题

    ## v1.1.0 (2024-01-10)
    - 添加用户搜索功能

7. 批量操作

# 批量验证多个文件
openspec validate ./specs/*.yaml

# 批量生成文档
openspec generate docs ./specs/ --output ./build/docs

8. 自动化检查脚本

#!/bin/bash
echo "验证 OpenAPI 规范..."
openspec validate openapi.yaml

echo "生成文档..."
openspec generate docs openapi.yaml --output ./docs

echo "文档检查完成!"

9. CI/CD 集成示例

# .github/workflows/docs.yml
name: API Docs Maintenance
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  validate-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Validate OpenAPI Spec
        run: |
          npm install -g openspec
          openspec validate openapi.yaml

      - name: Generate Docs
        run: |
          openspec generate docs openapi.yaml --output ./public/docs

      - name: Deploy Docs
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public/docs

最佳实践

项目结构组织

my-api/
├── openapi/
│   ├── openapi.yaml          # 主文件
│   ├── paths/                # 接口路径拆分
│   │   ├── users.yaml
│   │   └── products.yaml
│   └── components/           # 组件拆分
│       ├── schemas.yaml
│       └── parameters.yaml
├── docs/                     # 生成的文档
└── scripts/
    └── build-docs.sh         # 文档构建脚本

文档维护脚本

#!/bin/bash
# scripts/build-docs.sh

echo "🔄 开始更新 API 文档..."

# 验证规范
if ! openspec validate openapi.yaml; then
    echo "❌ OpenAPI 规范验证失败"
    exit 1
fi

# 生成文档
openspec generate docs openapi.yaml \
    --output ./docs \
    --theme redoc \
    --title "My API Documentation"

# 检查生成结果
if [ -d "./docs" ]; then
    echo "✅ 文档生成成功"
    echo "📁 文档位置: ./docs/index.html"
else
    echo "❌ 文档生成失败"
    exit 1
fi

变更管理

# 文档版本对比
openspec diff openapi.v1.yaml openapi.v2.yaml

# 生成变更报告
openspec generate changelog openapi.yaml --output CHANGELOG.md

维护技巧

定期验证：每次修改后运行 openspec validate
实时预览：开发时使用 openspec serve --watch
版本控制：为每个 API 版本维护独立的文档
自动化部署：集成到 CI/CD 流程自动发布更新
团队协作：建立文档更新和审查流程

常见命令速查

命令	功能	示例
`openspec init`	初始化项目	`openspec init my-api`
`openspec validate`	验证规范	`openspec validate openapi.yaml`
`openspec generate docs`	生成文档	`openspec generate docs --output ./docs`
`openspec serve`	启动预览服务器	`openspec serve --port 3000 --watch`
`openspec mock`	启动 Mock 服务	`openspec mock --port 8080`
`openspec diff`	对比版本差异	`openspec diff v1.yaml v2.yaml`
`openspec generate client`	生成客户端代码	`openspec generate client --language typescript`

应用场景

典型应用

API 优先开发：先定义接口规范，再实现代码
微服务架构：管理多个服务的 API 规范
团队协作：统一团队的 API 设计标准
文档维护：保持代码与文档的同步更新

适用团队

需要遵循 OpenAPI 规范的开发团队
追求 API 设计一致性的团队
需要自动化生成文档和代码的团队
实施微服务架构的组织

文档更新时间：2024年1月
OpenSpec 版本：最新稳定版

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search

OpenSpec 使用指南

概述

目录

OpenSpec Init 作用

主要功能

使用场景

OpenSpec 主要功能

核心功能模块

1. 规范管理

2. 代码生成

3. 文档相关

4. Mock 服务

工作流程示例

开发阶段

生产阶段

主要优势

文档维护流程

1. 初始化文档项目

2. 实时文档预览

3. 规范验证

4. 文档生成与导出

5. 版本化文档管理

6. API 更新维护

7. 批量操作

8. 自动化检查脚本

9. CI/CD 集成示例

最佳实践

项目结构组织

文档维护脚本

变更管理

维护技巧

常见命令速查

应用场景

典型应用

适用团队