您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

Azure Functions 中的 OpenAPI 2.0 元数据支持(预览版)OpenAPI 2.0 metadata support in Azure Functions (preview)

Azure Functions 中的 OpenAPI 2.0(以前称为 Swagger)元数据支持一项预览版功能,可用于在 Function App 中编写 OpenAPI 2.0 定义。OpenAPI 2.0 (formerly Swagger) metadata support in Azure Functions is a preview feature that you can use to write an OpenAPI 2.0 definition inside a function app. 随后可使用 Function App 托管该文件。You can then host that file by using the function app.

重要

OpenAPI 预览功能目前仅在 1.x 运行时可用。The OpenAPI preview feature is only available today in the 1.x runtime. 若要了解如何创建 1.x 函数应用,可参阅此处Information on how to create a 1.x function app can be found here.

通过 OpenAPI 元数据,大量其他软件可使用托管 REST API 的函数。OpenAPI metadata allows a function that's hosting a REST API to be consumed by a wide variety of other software. 此软件包括 Microsoft 产品/服务(如 PowerApps 和 Azure 应用服务的 API 应用功能)、第三方开发人员工具(如 Postman,以及更多大量的程序包This software includes Microsoft offerings like PowerApps and the API Apps feature of Azure App Service, third-party developer tools like Postman, and many more packages.

此参考信息面向 Azure Functions 开发人员。This is reference information for Azure Functions developers. Azure Functions 的新手请从以下资源入手:If you're new to Azure Functions, start with the following resources:

提示

建议先从入门教程开始,然后返回到本文档,了解有关特定功能的详细信息。We recommend starting with the getting started tutorial and then returning to this document to learn more about specific features.

启用 OpenAPI 定义支持Enable OpenAPI definition support

可在函数应用的“平台功能”的“API 定义”页中配置所有 OpenAPI 设置。You can configure all OpenAPI settings on the API Definition page in your function app's Platform features.

备注

beta 版本运行时当前不支持函数 API 定义功能。Function API definition feature is not supported for beta runtime currently.

要生成托管的 OpenAPI 定义和快速入门定义,请将“API 定义源”设置为“函数(预览版)”。To enable the generation of a hosted OpenAPI definition and a quickstart definition, set API definition source to Function (Preview). 外部 URL 允许函数使用托管在其他位置的 OpenAPI 定义。External URL allows your function to use an OpenAPI definition that's hosted elsewhere.

通过函数元数据生成 Swagger 框架Generate a Swagger skeleton from your function's metadata

模板可帮助你开始编写第一个 OpenAPI 定义。A template can help you start writing your first OpenAPI definition. 定义模板功能通过使用 function.json 文件中的所有元数据,为每个 HTTP 触发器函数创建稀疏的 OpenAPI 定义。The definition template feature creates a sparse OpenAPI definition by using all the metadata in the function.json file for each of your HTTP trigger functions. 将需要按 OpenAPI 规范填写 API 详细信息,如请求和响应模板。You'll need to fill in more information about your API from the OpenAPI specification, such as request and response templates.

有关分步说明,请参阅入门教程For step-by-step instructions, see the getting started tutorial.

可用模板Available templates

名称Name 描述Description
生成的定义Generated Definition 一个 OpenAPI 定义,内含可从函数的现有元数据中推断出的大量信息。An OpenAPI definition with the maximum amount of information that can be inferred from the function's existing metadata.

生成的定义中包含的元数据Included metadata in the generated definition

下表显示了 Azure 门户设置,并显示 function.json 在映射到生成的 Swagger 框架时包含的相应数据。The following table represents the Azure portal settings and corresponding data in function.json as it is mapped to the generated Swagger skeleton.

Swagger.jsonSwagger.json 门户 UIPortal UI Function.jsonFunction.json
主机Host “Function App 设置” > “应用服务设置” > “概述” > “URL”Function app settings > App Service settings > Overview > URL 不存在Not present
路径Paths “集成” > “选择 HTTP 方法”Integrate > Selected HTTP methods 绑定:路由Bindings: Route
路径项Path Item “集成” > “路由模板”Integrate > Route template 绑定:方法Bindings: Methods
安全性Security 密钥Keys 不存在Not present
operationID*operationID* 路由 + 允许的动作Route + Allowed verbs 路由 + 允许的动作Route + Allowed Verbs

*仅与 PowerApps 和 Flow 集成才需要操作 ID。*The operation ID is required only for integrating with PowerApps and Flow.

备注

x-ms-summary 扩展名在逻辑应用、PowerApps 和 Flow 中提供显示名称。The x-ms-summary extension provides a display name in Logic Apps, PowerApps, and Flow.

有关详细信息,请参阅自定义 PowerApps 的 Swagger 定义To learn more, see Customize your Swagger definition for PowerApps.

使用 CI/CD 设置 API 定义Use CI/CD to set an API definition

必须先在门户中启用 API 定义托管,然后源控件才能修改其中的 API 定义。You must enable API definition hosting in the portal before you enable source control to modify your API definition from source control. 请按照以下说明操作:Follow these instructions:

  1. 浏览到 Function App 设置中的“API 定义(预览)”。Browse to API Definition (preview) in your function app settings.
    1. 将“API 定义源”设置为“函数”。Set API definition source to Function.
    2. 单击“生成 API 定义模板”,然后单击“保存”以创建模板定义供稍后修改。Click Generate API definition template and then Save to create a template definition for modifying later.
    3. 记下 API 定义 URL 和密钥。Note your API definition URL and key.
  2. 设置持续集成/持续部署 (CI/CD)Set up continuous integration/continuous deployment (CI/CD).
  3. 在 \site\wwwroot.azurefunctions\swagger\swagger.json 处的源控件中修改 swagger.json。Modify swagger.json in source control at \site\wwwroot.azurefunctions\swagger\swagger.json.

现在,存储库中对 swagger.json 的更改就由 Function App 通过步骤 1.c 中记录的 API 定义 URL 和密码进行托管。Now, changes to swagger.json in your repository are hosted by your function app at the API definition URL and key that you noted in step 1.c.

后续步骤Next steps