ZGI 市场
登录注册账号
技能版本 1.0.0

openapi-spec-generation

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.

价格

免费

  • 安装：免费

在组织开通时一次性收取；再次读取清单或下载不重复收费。

以上为公开标价。你的组织可能有协议价，以控制台显示的价格为准。

如何使用

  1. 为组织安装

    开通即安装：组织固定使用开通时的版本（当前为 1.0.0）。升级到新版本需要取消后重新开通。

  2. 创建凭证

    客户端使用组织凭证读取；绑定到数字人后，数字人使用绑定凭证按需加载。请求中携带：

    Authorization: Bearer $ZGI_MARKET_KEY

  3. 读取清单与安装包

    清单列出版本、文件和校验值；安装包是一个 zip 文件。

    读取清单
    curl "https://market-api.zgi.im/v1/market/skills/openapi-spec-generation/manifest" \
  -H "Authorization: Bearer $ZGI_MARKET_KEY"
    下载安装包
    curl "https://market-api.zgi.im/v1/market/skills/openapi-spec-generation/package" \
  -H "Authorization: Bearer $ZGI_MARKET_KEY" \
  -o openapi-spec-generation.zip

    读取清单和下载安装包不计入用量。下载后请用响应头中的 SHA-256 校验文件。

技能说明

名称
openapi-spec-generation
说明
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.
仅指令

技能包内没有脚本文件：这个技能是供模型阅读的文本。

SKILL.md 节选

# 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

### Template 1: Complete API Specification

```yaml
openapi: 3.1.0
info:
  title: User Management API
  description: |
    API for managing users and their profiles.

    ## Authentication
    All endpoints require Bearer token authentication.

    ## Rate Limiting
    - 1000 requests per minute for standard tier
    - 10000 requests per minute for enterprise tier
  version: 2.0.0
  contact:
    name: API Support
    email: api-support@example.com
    url: https://docs.example.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.example.com/v2
    description: Production
  - url: https://staging-api.example.com/v2
    description: Staging
  - url: http://localhost:3000/v2
    description: Local development

tags:
  - name: Users
    description: User management operations
  - name: Profiles
    description: User profile operations
  - name: Admin
    description: Administrative operations

paths:
  /users:
    get:
      operationId: listUsers
      summary: List all users
      description: Returns a paginated list of users with optional filtering.
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - name: status
          in: query
          description: Filter by user status
          schema:
            $ref: '#/components/schemas/UserStatus'
        - name: search
          in: query
          description: Search by name or email
          schema:
            type: string
            minLength: 2
            maxLength: 100
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
              examples:
                default:
                  $ref: '#/components/examples/UserListExample'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
        - bearerAuth: []

    post:
      operationId: createUser
      summary: Create a new user
      description: Creates a new user account and sends welcome email.
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
            examples:
              standard:
                summary: Standard user
                value:
                  email: user@example.com
                  name: John Doe
                  role: user
              admin:
                summary: Admin user
                value:
                  email: admin@example.com
                  name: Admin User
                  role: admin
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:

SKILL.md 不止这些内容，安装后可阅读全文。

技能包内容

共 1 个文件，合计 24.1 KiB

  • SKILL.md24.1 KiB

来源与审核

审核状态
尚未审核，内容来自上游来源
来源文档
https://github.com/wshobson/agents
源代码仓库
https://github.com/wshobson/agents
许可证
未说明

审核状态是平台对上架信息的记录，不构成对上游服务质量或可用性的担保。

相关商品