---
id: gh-openapi-spec-generation
name: "openapi-spec-generation"
url: https://skills.yangsir.net/skill/gh-openapi-spec-generation
author: wshobson
domain: ai-backend-engineering
tags: ["openapi", "api-design", "api-documentation", "backend-development", "sdk-generation"]
install_count: 12700
rating: 4.50 (120 reviews)
github: https://github.com/wshobson/agents/tree/main/plugins/documentation-generation/skills/openapi-spec-generation
---

# openapi-spec-generation

> 此技能可帮助开发者高效生成和维护 OpenAPI 3.1 规范，支持从现有代码或设计优先模式创建。它能确保 API 合约的准确性与一致性，加速 API 文档生成、SDK 开发及跨团队协作，显著提升后端开发效率和API质量。

**Stats**: 12,700 installs · 4.5/5 (120 reviews)

## Before / After 对比

### API 规范更新效率

**Before**:

手动更新和维护复杂的 OpenAPI 规范耗时巨大，且极易引入错误，导致文档与实际 API 不符，严重阻碍开发进度和团队协作。

**After**:

通过自动化生成和验证，OpenAPI 规范能快速更新并保持与代码同步，大幅减少手动工作量，确保 API 合约的准确性和一致性。

| Metric | Before | After | Change |
|---|---|---|---|
| 规范更新时间 | 240分钟 | 15分钟 | -93% |

## Readme

# 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

```yaml
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


---
*Source: https://skills.yangsir.net/skill/gh-openapi-spec-generation*
*Markdown mirror: https://skills.yangsir.net/api/skill/gh-openapi-spec-generation/markdown*