首页 › 龙虾技能列表 › Openapi Spec — Openapi工具

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...

1· 162·1 当前·1 累计
by @codenova58·MIT-0
下载技能包
License
MIT-0
最后更新
2026/3/25
安全扫描
VirusTotal
无害
查看报告
OpenClaw
安全
high confidence
This is an instruction-only OpenAPI guidance skill whose requirements and runtime instructions align with its stated purpose and do not request additional credentials, installs, or system access.
评估建议
This skill is a documentation-only guidance pack for OpenAPI workflows and appears internally consistent. Before installing, consider: (1) the source is unknown—verify the publisher if provenance matters; (2) later steps you follow (e.g., running codegen, CI linters, or publishing) may require third-party tools, API keys, or network access—those will be separate actions outside this skill; and (3) as with any skill, review any future code or install steps it suggests before executing them.
详细分析 ▾
✓ 用途与能力
Name and description match the SKILL.md content: a multi-stage OpenAPI design/linting/codegen workflow. The skill does not request unrelated binaries, environment variables, or config paths.
✓ 指令范围
SKILL.md contains only guidance, checklists, and best practices for OpenAPI workflows. It does not instruct the agent to read files, access environment variables, call external endpoints, or run shell commands.
✓ 安装机制
No install spec or code files are present. Being instruction-only means nothing is written to disk or downloaded at install time.
✓ 凭证需求
No environment variables, credentials, or config paths are required or referenced; this is proportional for a documentation/workflow guidance skill.
✓ 持久化与权限
always is false and model invocation is allowed (default). The skill does not request permanent presence or attempt to modify other skills or system settings.
安全有层次，运行前请审查代码。

License

MIT-0

可自由使用、修改和再分发，无需署名。

运行时依赖

无特殊依赖

版本

latestv1.0.02026/3/25

- 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.

● 无害

安装命令 点击复制

官方npx clawhub@latest install openapi-spec
镜像加速npx clawhub@latest install openapi-spec --registry https://cn.clawhub-mirror.com

技能文档

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.
数据来源：ClawHub ↗ · 中文优化：龙虾技能库
OpenClaw 技能定制 / 插件定制 / 私有工作流定制

免费技能或插件可能存在安全风险，如需更匹配、更安全的方案，建议联系付费定制

了解定制服务