Communitygithub.com

YepAPI/skills

從 Zod 架構生成 OpenAPI 3.1 規格,搭配 Swagger/Scalar 互動式文件、版本化管理,並為每個端點提供範例請求。

skills 是什麼?

此技能旨在為開發者提供一套基於程式碼自動生成與維護 API 文件的完整解決方案。它強制以 Zod 架構(如 `zod-to-openapi` 或 `@asteasolutions/zod-to-openapi`)作為單一事實來源,取代手動撰寫 OpenAPI YAML 的繁瑣工作。這項技能支援 Hono、Express 等常見後端框架,並可透過 Scalar 或 Swagger UI 在 `/docs` 路徑提供互動式文件。其主要優勢在於確保文件與實作驗證邏輯完全同步,避免文件過時,並自動為每個端點產生包含真實資料範例的請求與回應說明。此外,技能也涵蓋了透過 URL 路徑(如 `/api/v1/`)進行版本管理、標準化的錯誤回應格式、以及將端點依資源(如 `/users`、`/products`)分組的最佳實務。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/YepAPI/skills/tree/HEAD/skills/api-documentation

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

API 文件

規則

  • 以 OpenAPI 3.1 規格作為單一事實來源 — 從程式碼生成,而非手動撰寫
  • Zod 架構轉換為 OpenAPI:使用 zod-openapi 或 @asteasolutions/zod-to-openapi — 一次定義,同時驗證與文件化
  • 互動式文件:Scalar(現代、快速)或 Swagger UI — 在 /docs 或 /api-docs 路徑提供服務
  • 每個端點都必須包含:摘要、說明、請求主體架構、所有回應碼及對應範例
  • 每個端點都要有範例請求/回應 — 使用貼近真實的資料,避免使用 "string" 這類佔位符
  • 版本管理策略:破壞性變更使用 URL 路徑(/api/v1/、/api/v2/) — 比標頭版本管理更簡單
  • 錯誤回應:統一文件化所有錯誤形狀 — { error: string, code: string, details?: object }
  • 認證機制:在安全方案區段中文件化認證機制(Bearer Token、API Key)
  • 按資源分組端點:/users、/products、/orders — 在文件 UI 中使用標籤(tags)進行分組

範例

// 在 Hono/Express 中使用 zod-to-openapi
import { z } from "zod";
import { extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";
extendZodWithOpenApi(z);

const UserSchema = z.object({
  id: z.string().uuid().openapi({ example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }),
  name: z.string().openapi({ example: "Jane Smith" }),
  email: z.string().email().openapi({ example: "[email protected]" }),
}).openapi("User");

const CreateUserSchema = UserSchema.omit({ id: true }).openapi("CreateUser");

// 註冊端點
registry.registerPath({
  method: "post",
  path: "/api/v1/users",
  summary: "建立使用者",
  request: { body: { content: { "application/json": { schema: CreateUserSchema } } } },
  responses: {
    201: { description: "使用者建立成功", content: { "application/json": { schema: UserSchema } } },
    400: { description: "驗證錯誤" },
  },
});

避免事項

  • 手動撰寫 OpenAPI YAML — 應從 Zod 架構或路由定義生成
  • 遺漏錯誤回應的文件化 — 務必文件化 400、401、403、404、500 狀態碼
  • 使用通用範例如 "string" 或 0 — 應使用能展現真實資料形狀的實際值
  • 文件與實作脫節 — 應從驗證用的相同架構生成規格

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

YepAPI/skills

WCAG 2.1 AA — semantic HTML, keyboard navigation, screen readers.

YepAPI/skills

Experiment setup, variant splitting, statistical significance, and feature flag integration.

YepAPI/skills

CRUD generators, data tables, user management, role-based access, and bulk operations.

YepAPI/skills

Monitor what ChatGPT and Gemini say about your brand using YepAPI.

YepAPI/skills

Queue workers with BullMQ/Inngest/Trigger.dev, job retries, dead letter queues, concurrency.

YepAPI/skills

Commander.js, interactive prompts with Clack, spinners, colors, config files, exit codes, and npm publishing.

YepAPI/skills

cmdk integration, Cmd+K trigger, fuzzy search, grouped actions, keyboard navigation, and dynamic action registration.

YepAPI/skills

Content planning with trend and sentiment data from YepAPI.

YepAPI/skills

Content calendar, keyword-driven planning, and content briefs.

YepAPI/skills

Theme switching with CSS variables, system preference detection, next-themes, and persistence.

YepAPI/skills

Threaded comments, @mentions, reactions, moderation queue, optimistic UI, and cursor pagination.

YepAPI/skills

Competitive analysis between domains using YepAPI.

YepAPI/skills

Layout grids, KPI cards, data tables with sorting/filtering, sidebar navigation, and responsive breakpoints.

YepAPI/skills

Data encryption — TLS everywhere, AES-256-GCM for PII, bcrypt passwords, encrypted backups.

YepAPI/skills

Chart patterns with Recharts/Nivo/D3, responsive containers, color scales, and accessibility.

YepAPI/skills

Drizzle schema definition, push vs migrate, type-safe queries, relations, transactions, and prepared statements.

YepAPI/skills

Upload handling, resize/compress, CDN delivery, blur placeholders, and next/image patterns.

YepAPI/skills

Local business and Google Maps research using YepAPI.

YepAPI/skills

Cursor-based pagination, IntersectionObserver, virtualized lists with @tanstack/react-virtual, and scroll position restoration.

YepAPI/skills

Chat UI components, streaming responses with AI SDK, context window management, and RAG patterns.

相關技能