📦 swagger-skills — swagger-技能s

swagger-技能s

swagger-技能s 是一个独立的 Swagger/OpenAPI 技能 生成工具。它可以根据接口文档链接编制新的接口调用资料，把 Swagger UI 或 OpenAPI/Swagger spec 转换为按 控制器 归类的 Python 调用文件、接口字段说明和功能集成索引。

适用场景

当你需要根据接口文档快速生成可调用、可检索、可维护的 API 技能 时使用本 技能：

从 Swagger UI 页面自动发现真实 OpenAPI/Swagger spec 地址。 从 OpenAPI 3.x 或 Swagger 2.0 规格生成接口调用 Python 文件。 按 控制器 聚合接口说明，方便定位业务能力。 将接口调用域名集中维护在统一配置文件中。 为每个接口生成一份调用逻辑和一份字段说明文档。 默认文档认证

如果 Swagger 文档需要登录或 Basic Auth，请在 config/sources.json 中显式填写文档认证信息：

用户名： 密码：

该认证只用于拉取 Swagger 文档。生成出来的业务接口调用文件不会硬编码业务系统凭据。

目录说明 scripts/build_swagger_技能.py：根据 Swagger UI/spec 链接生成接口 技能 内容。 scripts/swagger_命令行工具ent.py：生成器和接口调用代码共用的 HTTP 工具。 config/sources.example.json：Swagger 文档来源配置示例。 生成d/：实际产出的业务接口 技能s；这些产物里的 技能.md 会按具体接口文档生成业务化说明，而不是复制本生成器的说明。 使用流程 将 config/sources.example.json 复制为 config/sources.json。 在 config/sources.json 中填写一个或多个 Swagger UI 页面链接或 spec 链接。 安装依赖后执行生成命令。 cd python -m pip 安装 -r requirements.txt python scripts\build_swagger_技能.py --清理-生成d

如果 sources.json 包含多个链接，生成器会询问产出方式： combined：多个接口文档合并产出 1 个 技能。 separate：每个接口文档分别产出 1 个 技能。 生成完成后，进入同级目录下具体产出的 技能，例如 ..\admin-config-swagger-技能s\，从 FEATURES.md 按功能查找接口，再进入对应的 API_命令行工具ents/<控制器>/.py 和 references/<控制器>/_OPENAPI.md。 输出约定

实际产出的业务 技能s 默认位于 swagger-技能s 的同级目录下，避免生成器 技能 和产物 技能 被同一个父目录扫描时重复注册：

合并模式：..\combined-swagger-技能s\ 分开模式：..\-swagger-技能s\

产出物的文件夹和文件名只使用英文、数字和下划线。生成器会优先使用英文 tag、operationId、path 片段或 source_id；中文名称不会转换为拼音，也不会直接进入路径。

同一个 控制器 下的接口会聚合到一个 控制器 说明文件中，同时每个具体接口会产生两个关联文件：

API_命令行工具ents/<控制器>/.py references/<控制器>/_OPENAPI.md

config/domAIns.json 会记录每份接口文档对应的调用域名、spec 地址和文档认证设置。