AGENT SKILL

openapi-spec

暂无简介

License 许可
MIT
最近更新
2026-03-27
Stars
★ 3
Forks
1

03 SKILL.md 正文

OpenAPI 3.x Specification Patterns

Structure

openapi: 3.1.0
info:
  title: API Name
  version: 1.0.0
paths:
  /resource:
    get:
      operationId: listResources
      tags: [resources]
      parameters: [{ $ref: '#/components/parameters/Pagination' }]
      responses:
        '200': { $ref: '#/components/responses/ResourceList' }
components:
  schemas: {}
  parameters: {}
  responses: {}
  securitySchemes: {}

Best Practices

  • operationId: camelCase, unique per operation (getUser, listOrders)
  • Tags: Group endpoints by domain, one primary tag per operation
  • $ref everything: Reuse schemas, parameters, responses via $ref
  • Schema composition: allOf for inheritance, oneOf for unions, discriminator for polymorphism
  • Pagination: Standardize with shared parameter + response schema
  • Error responses: Consistent { code: string, message: string } schema across all errors

Next.js API Routes

  • next-swagger-doc: Auto-generate OpenAPI spec from JSDoc comments
  • swagger-jsdoc: Annotate route handlers with @openapi blocks
  • Serve spec at /api/docs or /api/openapi.json

Code Generation

  • openapi-typescript: Generate TypeScript types from spec
  • orval or openapi-codegen: Generate API client + React Query hooks
  • Validate at CI: spectral lint openapi.yaml

Versioning

  • URL path versioning: /api/v1/resource (explicit, easy to route)
  • Header versioning: Accept: application/vnd.api.v1+json (cleaner URLs)
  • Keep old versions documented until sunset date

04 同仓库更多 Skills

ByeongminLee
ByeongminLee/nextjs-claude-code

zustand

Zustand state management guide. Use when working with store code (src/store/**), implementing actions, managing state, or creating slices. Triggers on Zustand store development, state management questions, or action implementation.

★ 3
ByeongminLee
ByeongminLee/nextjs-claude-code

web-vitals

暂无简介

★ 3
ByeongminLee
ByeongminLee/nextjs-claude-code

vercel-storage

Vercel storage expert guidance — Blob, Edge Config, and Marketplace storage (Neon Postgres, Upstash Redis). Use when choosing, configuring, or using data storage with Vercel applications.

后端与接口
★ 3
ByeongminLee
ByeongminLee/nextjs-claude-code

vercel-functions

Vercel Functions expert guidance — Serverless Functions, Edge Functions, Fluid Compute, streaming, Cron Jobs, and runtime configuration. Use when configuring, debugging, or optimizing server-side code running on Vercel.

开发工程师后端与接口
★ 3
ByeongminLee
ByeongminLee/nextjs-claude-code

ui-ux-pro-max

UI/UX design intelligence for web and mobile. Includes 50+ styles, 161 color palettes, 57 font pairings, 161 product types, 99 UX guidelines, and 25 chart types across 10 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui, and HTML/CSS). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, and check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, and mobile app. Elements: button, modal, navbar, sidebar, card, table, form, and chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, and flat design. Topics: color systems, accessibility, animation, layout, typography, font pairing, spacing, interaction states, shadow, and gradient. Integrations: shadcn/ui MCP for component search and examples.

设计师数据分析师前端开发视觉设计
★ 3
ByeongminLee
ByeongminLee/nextjs-claude-code

turborepo

Turborepo monorepo build system guidance. Triggers on: turbo.json, task pipelines, dependsOn, caching, remote cache, the "turbo" CLI, --filter, --affected, CI optimization, environment variables, internal packages, monorepo structure/best practices, and boundaries. Use when user: configures tasks/workflows/pipelines, creates packages, sets up monorepo, shares code between apps, runs changed/affected packages, debugs cache, or has apps/packages directories.

★ 3