openapi-spec-generation – skill Lập trình cho agent AI

Tạo và duy trì đặc tả OpenAPI 3.1 từ mã nguồn, đặc tả thiết kế trước (design-first) và các mẫu xác thực. Dùng khi tạo tài liệu API, sinh SDK hoặc đảm bảo tuân thủ hợp đồng API.

Lập trìnhSKILL.mdClaude Code · Codex · Hermes · DeepSeek

Cài skill openapi-spec-generation bằng một lệnh

Chọn công cụ bạn đang dùng, copy lệnh và dán vào terminal. Skill sẽ nằm trong thư mục skills của công cụ đó và sẵn sàng dùng ở phiên làm việc tiếp theo.

Claude Code

mkdir -p ~/.claude/skills && curl -fsSL https://skill.dn1nguoi.com/z/openapi-spec-generation-e1733.tgz | tar xz -C ~/.claude/skills

Gọi trong Claude Code: /openapi-spec-generation – rồi mô tả công việc bạn muốn làm.

Codex

mkdir -p ~/.codex/skills && curl -fsSL https://skill.dn1nguoi.com/z/openapi-spec-generation-e1733.tgz | tar xz -C ~/.codex/skills

Gọi trong Codex: $openapi-spec-generation – rồi mô tả công việc bạn muốn làm.

Hermes Agent

mkdir -p ~/.hermes/skills && curl -fsSL https://skill.dn1nguoi.com/z/openapi-spec-generation-e1733.tgz | tar xz -C ~/.hermes/skills

Gọi trong Hermes Agent: /openapi-spec-generation – rồi mô tả công việc bạn muốn làm.

DeepSeek

mkdir -p ~/.deepcode/skills && curl -fsSL https://skill.dn1nguoi.com/z/openapi-spec-generation-e1733.tgz | tar xz -C ~/.deepcode/skills

Gọi trong DeepSeek: /openapi-spec-generation – rồi mô tả công việc bạn muốn làm.

Nội dung SKILL.md

Nội dung SKILL.md gốc bằng tiếng Anh.

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

Skill liên quan

parallel-debugging – Gỡ lỗi các vấn đề phức tạp bằng cách đưa ra các giả thuyết cạnh tranh, điều tra song…
hunt-source-leak – Săn lỗ hổng rò rỉ mã nguồn và artifact build: source map JavaScript (.js.map) khôi phục…
azure-storage-blob-rust – SDK Azure Blob Storage cho Rust. Dùng để tải lên, tải xuống và quản lý blob cùng…
azure-storage-queue-rust – Thư viện Azure Queue Storage cho Rust. Gửi, nhận và quản lý tin nhắn hàng đợi. Kích hoạt…
site-architecture – Khi người dùng muốn lên kế hoạch, lập bản đồ hoặc tái cấu trúc cấu trúc phân cấp trang…
babysit-pr – Theo sát pull request qua các vòng review của bot: kiểm tra, sửa, trả lời, đánh dấu đã…
backend-architect – Kiến trúc sư backend chuyên về thiết kế API có khả năng mở rộng, kiến trúc microservices…
backend-dev-guidelines – Bạn là kỹ sư backend cao cấp vận hành các dịch vụ production theo ràng buộc nghiêm ngặt…

← Xem tất cả skill