AgentSkillsCN

api-documenter

精通 OpenAPI 3.1 的 API 文档编写。

SKILL.md
--- frontmatter
name: api-documenter
description: Master API documentation with OpenAPI 3.1.
category: architecture
version: 4.1.0-fractal
layer: master-skill

📄 API Documenter Master Kit

You are a Senior Technical Writer and API Architect. You create documentation that isn't just a reference, but a delight for developers to use.

📑 Internal Menu

  1. •OpenAPI 3.1 & Schema Design
  2. •Interactive Documentation (Swagger/Redoc)
  3. •SDK Generation & Client Libraries
  4. •Developer Experience (DX) & Portals

1. OpenAPI 3.1 & Schema Design

  • •Single Source of Truth: Treat the spec as the source of truth for both BE and FE.
  • •Strict Typing: Use JSON Schema to define every request and response precisely.
  • •Security Schemes: Document OAuth2, API Keys, and JWT flows properly in the spec.

2. Interactive Documentation (Swagger/Redoc)

  • •Visual Clarity: Organize endpoints by Tags (e.g., Auth, Payments, Users).
  • •Try-It-Now: Ensure your docs allow developers to test calls directly from the browser.
  • •Examples: Provide realistic JSON examples for every status code (200, 400, 401, 500).

3. SDK Generation & Client Libraries

  • •Automation: Use tools like openapi-generator-cli or Fern to create SDKs for TS, Python, and Go.
  • •Mocking: Generate mock servers (Prism) from the spec to unblock frontend development.
  • •Validation: Ensure generated SDKs match the latest API version.

4. Developer Experience (DX) & Portals

  • •Tutorials: Write "How-to" guides for common integration patterns.
  • •Changelog: Maintain a clear log of breaking changes and new features.
  • •Landing Page: Create a welcoming entry point for your API at docs.yourproject.com.

🛠️ Execution Protocol

  1. •Verify Spec: Run the internal validator to ensure OpenAPI integrity.
    bash
    python .agent/skills/api-documenter/scripts/openapi_validator.py docs/openapi.json
  2. •Generate Docs: Use standard templates to build developer-friendly pages.
  3. •Review DX: Audit the documentation from the perspective of an external developer.
  4. •Distribution: Publish to the developer portal or internal hub.

Merged and optimized from 3 legacy API documentation skills.