Openapi Spec — Openapi工具
v1.0.0[AI辅助] Deep OpenAPI workflow—design-first vs code-first, reusable schemas, security schemes, errors, examples, linting, compatibility, and codegen. Use when documen...
by 详细分析 ▾
运行时依赖
版本
- Initial release of the OpenAPI Spec skill with a detailed, stage-based workflow for REST API specification. - Covers design-first vs code-first, ownership, versioning, RESTful conventions, reusable schemas, security schemes, error patterns, linting, and compatibility checks. - Provides a practical final review checklist and best practices for robust API contracts. - Includes guidance for handling deviations (e.g., using GraphQL elsewhere) and tips for maintaining examples and schema consistency.
安装命令
点击复制本土化适配说明
Openapi Spec — Openapi工具 安装说明： 安装命令：npx clawhub@latest install openapi-spec
技能文档
OpenAPI is the contract between teams and tools. Quality comes from consistent schemas, realistic examples, and lint rules that catch breaking changes early.
当...时 到 Offer Workflow
Trigger conditions:
- 新的 REST API; 公开 或 partner surface
- Codegen 对于 clients/servers; API gateway validation 从 spec
- Drift 之间 docs 和 implementation
Initial offer:
Use six stages: (1) workflow choice & ownership, (2) info & versioning, (3) resources & operations, (4) schemas & components, (5) security & errors, (6) lint, compatibility & publish). Confirm OpenAPI 3.x and style guide.
Stage 1: Workflow & Ownership
Goal: Design-第一个 (spec → implement) vs code-第一个 (annotations → 导出)—pick one per 服务 和 enforce.
Ownership
- 谁 approves breaking changes; 在哪里 spec lives 在...中 repo
Exit 条件: Single source 的 truth 对于 API contract.
Stage 2: Info & Versioning
Goal: info.title, version scheme aligned 带有 URL 或 页头 versioning strategy.
Practices
- Deprecation policy 在...中 description 或 扩展 fields
Stage 3: Resources & Operations
Goal: RESTful naming 在哪里 appropriate; operationId stable 对于 codegen.
Practices
- 分页 (
cursor/page), filtering, 排序 documented - Idempotency (
Idempotency-键) 对于 unsafe retries 当...时 relevant
Stage 4: Schemas & Components
Goal: components/schemas reused; nullable vs 可选 正确 在...中 JSON Schema sense.
Practices
- OneOf discriminated unions 对于 polymorphic payloads 当...时 needed
- Examples per schema 对于 human 和 machine readers
Stage 5: Security & Errors
Goal: securitySchemes (Bearer, OAuth2) applied per operation 或 globally.
Errors
- Problem Details (
application/problem+json) pattern 带有 stable类型URIs
Stage 6: Lint, Compatibility & 发布
Goal: Spectral 或 vacuum rules 在...中 CI; openapi-diff 在...上 PRs.
发布
- Docs portal (Swagger UI, Redoc); postman collections 可选
Final Review Checklist
- [ ] Single ownership 和 design-第一个 或 code-第一个 discipline
- [ ] Versioning 和 deprecation story 清除
- [ ] Operations complete 带有 分页/errors 作为 needed
- [ ] Reusable components 和 examples
- [ ] Security 和 错误 模型 consistent
- [ ] CI lint 和 breaking-更改 detection
Tips 对于 Effective Guidance
- Examples 应该 复制-paste 有效—catch enum drift.
- Nullable 在...中 OpenAPI 3.1 aligns 带有 JSON Schema—mind 3.0 differences 当...时 mixing.
- Internal APIs 仍然 benefit 从 相同 rigor—future 您 partner team.
Handling Deviations
- GraphQL elsewhere: OpenAPI 对于 REST edge 仅—don’t force one doc 对于 both.