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:
allOffor inheritance,oneOffor unions,discriminatorfor 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 commentsswagger-jsdoc: Annotate route handlers with@openapiblocks- Serve spec at
/api/docsor/api/openapi.json
Code Generation
openapi-typescript: Generate TypeScript types from specorvaloropenapi-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
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.
web-vitals
暂无简介
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.
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.
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.
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.