api-documenter 是一个围绕 API 文档生成与维护的技能,出自 thinkfleetai/thinkfleet-engine 项目。其核心目标是从代码和 OpenAPI 规范出发,生成并维护 API 文档。以下按用途、主要能力、使用方式、适用场景和限制进行说明。
用途
用于生成和维护 API 文档。技能说明指出,可以生成 OpenAPI 3.1 规范、使用 Swagger/Redoc 生成交互式文档、生成 SDK,以及提取 JSDoc/TSDoc 文档。
主要能力
- OpenAPI 规范校验与合并:使用
npx @apidevtools/swagger-cli validate openapi.yaml校验规范;使用npx @apidevtools/swagger-cli bundle openapi.yaml -o openapi-bundled.yaml将拆分文件合并为一个。 - 交互式文档:Swagger UI 可通过
npx @redocly/cli preview openapi.yaml本地预览,或用 Docker 运行docker run -p 8080:8080 -e SWAGGER_JSON=/spec/openapi.yaml -v $(pwd):/spec swaggerapi/swagger-ui;Redoc 可用npx @redocly/cli build-docs openapi.yaml -o docs.html生成静态 HTML,或用npx @redocly/cli preview-docs openapi.yaml预览并热重载。 - 从代码生成 OpenAPI:Express/Node.js 使用 swagger-jsdoc,安装
npm install swagger-jsdoc swagger-ui-express,并通过 JSDoc 注解生成规范;FastAPI(Python)自动在 /docs 生成 OpenAPI,可用curl -s http://localhost:8000/openapi.json | jq . > openapi.json导出。 - TypeDoc 与 JSDoc 提取:TypeDoc 可用
npx typedoc --entryPoints src/index.ts --out docs/api生成文档,支持--json docs/api.json输出 JSON,以及--readme README.md;JSDoc 可用npx jsdoc src/ -r -d docs/生成 HTML,并支持自定义模板如-t node_modules/clean-jsdoc-theme。 - SDK 生成:
npx openapi-typescript openapi.yaml -o src/api-types.ts生成 TypeScript 客户端类型;使用 openapi-generator 可生成完整 SDK,如 TypeScript(-g typescript-fetch)与 Python(-g python),输出到指定目录。 - OpenAPI lint:Redocly 使用
npx @redocly/cli lint openapi.yaml;Spectral 使用npx @stoplight/spectral-cli lint openapi.yaml。
使用方式
所有操作均通过命令行完成,主要依赖 npx、npm、docker、curl 等工具。
适用场景与限制
技能建议采用“设计优先”的方式,先编写 OpenAPI 规范再实现,对团队而言比代码优先更快;主张将规范与代码一起纳入版本控制,并在 CI 中校验规范,因为损坏的文档比没有文档更糟。SDK 生成可为客户端团队节省大量时间,建议每次 API 变更后重新生成。对于大型规范,建议使用 $ref 拆分为更易管理的文件。除上述内容外,关于收费、价格、平台限制等信息暂未提供。