SuperAPI AI 工具集

api-documenter

编程与开发

查看项目

更新于 10-16 06:56

技能介绍

api-documenter 是一个围绕 API 文档生成与维护的技能,出自 thinkfleetai/thinkfleet-engine 项目。其核心目标是从代码和 OpenAPI 规范出发,生成并维护 API 文档。以下按用途、主要能力、使用方式、适用场景和限制进行说明。

用途

用于生成和维护 API 文档。技能说明指出,可以生成 OpenAPI 3.1 规范、使用 Swagger/Redoc 生成交互式文档、生成 SDK,以及提取 JSDoc/TSDoc 文档。

主要能力

  1. OpenAPI 规范校验与合并:使用 npx @apidevtools/swagger-cli validate openapi.yaml 校验规范;使用 npx @apidevtools/swagger-cli bundle openapi.yaml -o openapi-bundled.yaml 将拆分文件合并为一个。
  2. 交互式文档: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 预览并热重载。
  3. 从代码生成 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 导出。
  4. 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。
  5. SDK 生成:npx openapi-typescript openapi.yaml -o src/api-types.ts 生成 TypeScript 客户端类型;使用 openapi-generator 可生成完整 SDK,如 TypeScript(-g typescript-fetch)与 Python(-g python),输出到指定目录。
  6. 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 拆分为更易管理的文件。除上述内容外,关于收费、价格、平台限制等信息暂未提供。