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 产品/服务(如 Azure 应用服务的 API 应用功能)、第三方开发人员工具(如 Postman),以及更多包This software includes Microsoft offerings like 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


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

后续步骤Next steps