360 Secure SkillHub
360 安全技能中心

OpenAPI Docs Generator

核心功能为生成、修复、验证REST API的OpenAPI/Swagger文档，能梳理API路由、schema、示例等信息，排查文档与实现的差异，输出规范文档片段、 gap修复建议、验证命令及各类场景示例。适用于API缺少规范、文档与实现不符、无法适配下游工具的场景，面向后端工程师等负责API文档的人员。

kyro-ma
kyro-ma
热度 16.02
最近更新 2026-06-23 12:33:51
分类：开发依赖：纯提示词应用场景：API 集成 / 代码审查 / 工作流

安装技能

复制下面的话术发给你的 Agent，它会通过 secure-skills 检索并安装该技能。

执行命令安装此 skill： npx secure-skills-cli add openapi-docs-generator-040526
Metadata
name
openapi-docs-generator
description
Generate, repair, and validate OpenAPI or Swagger documentation for REST APIs from routes, handlers, schemas, examples, and observed behavior. Use when a user asks for OpenAPI, Swagger, REST API, API docs, schema, or needs practical workflow, code, checklist, documentation, or review support for this job.

OpenAPI Docs Generator

Purpose

Use this skill when an API lacks an OpenAPI spec, the current spec drifts from implementation, examples are missing, or docs fail downstream SDK, gateway, or contract-test tooling.

Audience: backend engineers, platform teams, SDK maintainers, and developer-experience teams responsible for accurate REST API documentation.

Read references/requirement-plan.md when demand evidence, source links, scoring rationale, or review criteria are needed.

Workflow

  1. Inventory base URLs, auth, routes, controllers, schema validators, request samples, response samples, and existing OpenAPI fragments.
  2. Map each operation to method, path, parameters, request body, responses, errors, auth, idempotency, pagination, and rate limits.
  3. Draft or patch the OpenAPI document with reusable components for schemas, security schemes, errors, and shared parameters.
  4. Add realistic examples that match production constraints while redacting secrets and customer data.
  5. Validate with an OpenAPI parser or linter, then note contract mismatches that require code or docs changes.
  6. Return the spec changes, validation command, and follow-up tasks for SDK generation, docs publishing, or CI enforcement.

Expected Outputs

  • A new or patched OpenAPI YAML/JSON fragment.
  • Endpoint-by-endpoint documentation gaps and proposed fixes.
  • Validation commands for linting, bundling, SDK generation, or contract tests.
  • Examples for success, validation failure, authorization failure, and rate limits.

Validation

  • Every operation has method, path, auth, parameters, request body, responses, and examples where relevant.
  • Schemas reuse components instead of duplicating incompatible shapes.
  • The spec is parseable by standard OpenAPI tooling and does not include secrets.
  • Known implementation/spec drift is called out clearly.

Triggers

Keywords: OpenAPI, Swagger, REST API, API docs, schema, SDK, contract testing

Example trigger sentences:

  • Use $openapi-docs-generator to create an OpenAPI spec from these Express routes.
  • Patch this Swagger file so it matches the handler responses.
  • Review our API docs for missing schemas and examples.