Agent Skills
› wshobson/agents
› openapi-spec-generation
openapi-spec-generation
GitHub用于创建、维护和验证 OpenAPI 3.1 规范，支持从代码生成或设计优先模式，确保 API 契约合规并生成 SDK。
Trigger Scenarios
创建 API 文档
从代码生成 OpenAPI 规范
设计 API 契约
验证 API 实现
Install
npx skills add wshobson/agents --skill openapi-spec-generation -g -y
SKILL.md
Frontmatter
{
"name": "openapi-spec-generation",
"description": "Generate and maintain OpenAPI 3.1 specifications from code, design-first specs, and validation patterns. Use when creating API documentation, generating SDKs, or ensuring API contract compliance."
}
OpenAPI Spec Generation
Comprehensive patterns for creating, maintaining, and validating OpenAPI 3.1 specifications for RESTful APIs.
When to Use This Skill
- Creating API documentation from scratch
- Generating OpenAPI specs from existing code
- Designing API contracts (design-first approach)
- Validating API implementations against specs
- Generating client SDKs from specs
- Setting up API documentation portals
Core Concepts
1. OpenAPI 3.1 Structure
openapi: 3.1.0
info:
title: API Title
version: 1.0.0
servers:
- url: https://api.example.com/v1
paths:
/resources:
get: ...
components:
schemas: ...
securitySchemes: ...
2. Design Approaches
| Approach | Description | Best For |
|---|---|---|
| Design-First | Write spec before code | New APIs, contracts |
| Code-First | Generate spec from code | Existing APIs |
| Hybrid | Annotate code, generate spec | Evolving APIs |
Templates and detailed worked examples
Full template library and detailed worked examples live in references/details.md. Read that file when you need the concrete templates.
Best Practices
Do's
- Use $ref - Reuse schemas, parameters, responses
- Add examples - Real-world values help consumers
- Document errors - All possible error codes
- Version your API - In URL or header
- Use semantic versioning - For spec changes
Don'ts
- Don't use generic descriptions - Be specific
- Don't skip security - Define all schemes
- Don't forget nullable - Be explicit about null
- Don't mix styles - Consistent naming throughout
- Don't hardcode URLs - Use server variables
Version History
- 367cb6a Current 2026-08-20 06:51
