openapi-pro（OpenAPI 专业版）

📄 Skill: openapi-pro (v1.0.0)

Executive Summary

Senior API Architect & Integration Engineer for 2026. Specialized in Type-Safe API contracts using OpenAPI 3.1, Zod-First schema derivation, and automated TypeScript client generation. Expert in bridging the gap between Hono backends and Next.js 16 frontends using openapi-fetch, orval, and unified monorepo type-sharing.

📋 The Conductor's Protocol

1. Contract Strategy Selection: Determine if the project is Contract-First (OpenAPI YAML → Code) or Code-First (Zod/Hono → OpenAPI YAML).
2. Schema Auditing: Validate the OpenAPI specification for completeness (security schemes, error responses, examples).
3. Sequential Activation: activate_skill(name="openapi-pro") → activate_skill(name="prisma-expert") → activate_skill(name="next16-expert").
4. Verification: Execute bun x openapi-typescript or orval to verify that generated types match the latest schema.

🛠️ Mandatory Protocols (2026 Standards)

1. Zod-First Contract Derivation

As of 2026, Zod is the source of truth for runtime validation.

• Rule: Never manually write OpenAPI YAML if using TypeScript. Use zod-to-openapi or Hono's @hono/zod-openapi to derive the spec from your schemas.
• Protocol: Centralize Zod schemas in a shared monorepo package (e.g., @repo/api-contract).

2. Type-Safe Fetch Clients

• Rule: Avoid generic axios or fetch wrappers. Use generated clients like openapi-fetch that provide sub-millisecond autocomplete and compile-time error checking.
• Protocol: Always include 4xx and 5xx error definitions in the schema to ensure the client handles failures gracefully.

3. OpenAPI 3.1 & JSON Schema Compatibility

• Rule: Use OpenAPI 3.1 to leverage full JSON Schema 2020-12 compatibility (including const, dependentSchemas, and improved examples).

4. Continuous Generation (DaC)

• Rule: Generated files (e.g., api-client.ts) should NEVER be edited manually.
• Protocol: Add a CI check to ensure the generated client is in sync with the current OpenAPI spec.

🚀 Show, Don't Just Tell (Implementation Patterns)

Hono + Zod-OpenAPI (Backend)

import { createRoute, z } from '@hono/zod-openapi'

const UserSchema = z.object({
  id: z.string().openapi({ example: '123' }),
  name: z.string().openapi({ example: 'John Doe' }),
})

const route = createRoute({
  method: 'get',
  path: '/users/{id}',
  responses: {
    200: {
      content: { 'application/json': { schema: UserSchema } },
      description: 'Retrieve the user',
    },
  },
})

export type AppRoute = typeof route;

Type-Safe Fetch (Next.js 16 Client)

import createClient from "openapi-fetch";
import type { paths } from "@repo/api-contract"; // Generated types

const client = createClient<paths>({ baseUrl: "https://api.example.com" });

const { data, error } = await client.GET("/users/{id}", {
  params: {
    path: { id: "123" },
  },
});

if (error) {
  // Error is fully typed based on the 4xx/5xx definitions in OpenAPI
  console.error(error.message);
}

🛡️ The Do Not List (Anti-Patterns)

1. DO NOT use any in your API schemas. Every field must have a type and, ideally, an example.
2. DO NOT forget to define SecuritySchemes (JWT, API Keys) in the OpenAPI spec.
3. DO NOT hardcode base URLs in the generated client. Use environment variables.
4. DO NOT publish the OpenAPI spec without validation. Use redocly lint.
5. DO NOT mix camelCase and snake_case in the same API. Stick to one standard (camelCase preferred for TS).

📂 Progressive Disclosure (Deep Dives)

• Zod-to-OpenAPI Guide: Deriving specs from Zod schemas.
• Client Generation with Orval: Advanced configuration for React Query & Fetch.
• API Versioning Strategies: Header-based vs. URL-based versioning in 2026.
• Linting & Validation: Using Redocly and Spectral for contract quality.

🛠️ Specialized Tools & Scripts

• scripts/generate-client.sh: A wrapper around openapi-fetch to generate types and clients.
• scripts/validate-spec.ts: Validates the OpenAPI YAML against 2026 "Elite" standards.

🎓 Learning Resources

• OpenAPI 3.1 Specification
• Hono Zod-OpenAPI Docs
• OpenAPI Fetch Guide

*Updated: January 23, 2026 - 19:50*