如何为现有应用及Azure AI资源生成OpenAPI定义以构建Power Apps自定义连接器？

一、为已有应用生成OpenAPI定义 #

针对自建应用，可通过以下方式生成符合要求的OpenAPI定义：

• 手动编写：如果API规模较小，直接遵循OpenAPI 3.x规范编写JSON/YAML文件，重点明确基础路径、接口端点、请求/响应数据结构、认证规则等核心内容，Power Apps自定义连接器兼容这两种格式。
• 借助代码生成工具：
  • .NET开发的应用：集成Swashbuckle.AspNetCore包，在启动类中配置Swagger服务，启动后访问/swagger/v1/swagger.json即可导出OpenAPI JSON文件。
  • Node.js开发的应用：使用swagger-jsdoc或express-swagger-generator工具，通过代码注释或配置文件自动生成规范定义。
• 抓包逆向生成：若无应用源码，用Postman、Insomnia等工具录制API请求流程，导出为OpenAPI格式后，手动补全缺失的响应模型、认证逻辑等细节。

二、获取Azure AI资源（以计算机视觉为例）的OpenAPI定义 #

Azure AI服务的OpenAPI定义可通过以下途径获取：

• Azure门户直接下载：
  1. 进入目标计算机视觉资源的门户页面，在左侧菜单找到「API文档」或「Swagger」选项。
  2. 在Swagger页面顶部点击「下载JSON」按钮，直接获取对应资源的OpenAPI JSON文件。
• Azure CLI命令导出：
  运行以下命令（替换占位符为你的实际资源信息）：

  az rest --method get --uri "https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/swagger?api-version=2023-05-01"
  

  命令返回的JSON内容即为该计算机视觉资源的OpenAPI定义，保存为文件即可使用。
• Power Apps直接导入：
  在Power Apps创建自定义连接器时，选择「导入OpenAPI文件」，也可直接输入Azure AI服务的Swagger URL（格式示例：https://{your-resource-name}.cognitiveservices.azure.com/swagger/v1.0/swagger.json），系统会自动加载并解析定义。

注意：导入到Power Apps前，需确保OpenAPI定义中的认证方式（如Azure AI常用的API密钥认证）已配置对应的安全Scheme，保证连接器能正常调用服务。

内容的提问来源于stack exchange，提问作者CigarDoug