@aaronpowell/azure-functions-nodejs-openapi 中文文档教程

Question

OpenAPI for Azure Functions

这是 Azure Functions 的扩展，支持生成 <来自带注释的 Azure Functions 的 href="https://www.openapis.org/">OpenAPI 规范文件。 为了使这更容易，扩展是用 TypeScript 编写的，并为需要创建的对象提供了 TypeScript 类型。

该插件通过特定导入支持 OpenAPI/Swagger v2、v3 和 v3.1 的三个主要版本，默认导出为 OpenAPI 3.1。

该插件的灵感来自 .NET 扩展。

Usage

Step 1 - Annotate an Azure Function

导入所需的版本帮助器以使用 OpenAPI 的元数据注释 Azure Functions。

import { AzureFunction, Context, HttpRequest } from "@azure/functions";
import { mapOpenApi3_1 } from "@aaronpowell/azure-functions-nodejs-openapi";

const httpTrigger: AzureFunction = async function (
  context: Context,
  req: HttpRequest
): Promise<void> {
  context.log("HTTP trigger function processed a request.");
  const name = req.query.name;
  const responseMessage = name
    ? "Hello, " + name + ". This HTTP triggered function executed successfully."
    : "This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response.";

  context.res = {
    body: responseMessage,
  };
};

export default mapOpenApi3_1(httpTrigger, "/get-message", {
  get: {
    parameters: [
      {
        name: "name",
        in: "query",
        required: true,
        schema: {
          type: "string",
        },
      },
    ],
    responses: {
      "200": {
        description: "Gets a message from the Function",
        content: {
          "application/json": {
            example:
              "Hello Aaron. This is a HTTP triggered function executed successfully.",
          },
        },
      },
    },
  },
});

Step 2 - Create the OpenAPI endpoint

创建一个新的 HTTP 触发器 Azure Functions 并将其命名为您希望它向消费者公开的方式（例如 swagger），然后导入该函数以生成规范文件：

import { generateOpenApi3_1Spec } from "@aaronpowell/azure-functions-nodejs-openapi";

export default generateOpenApi3_1Spec({
  info: {
    title: "Azure Function Swagger v3.1 demo",
    version: "1.0.0",
  },
});

注意：您需要编辑function.json 将 out 参数命名为 res，因为生成器函数会将其分配给 context.

Examples

您可以在文件夹 example 中找到不同 OpenAPI 版本的示例。 它们在 Azure Functions 运行时版本 3.x 上运行。 如果您想在版本 4.x 上运行它们，请将 host.json 中的扩展包引用调整为：

"extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[2.*, 3.0.0)"
  }

Scaffolding Function descriptions

em>以下是正在进行的工作。

< 从为 Functions 生成 OpenAPI 注释开始，有一个 CLI 工具作为这个包的一部分提供，openapi-func。

这将查看函数的 function.json 并提供一些入门所需的样板。

cd example/trivia-app
npx openapi-func endpoint -f ./game-get

这将输出以下内容供您添加到您的函数中：

Here's a starting point for your OpenAPI enabled Function

Change the default export from the Azure Function to the following:

export default mapOpenApi3_1(httpTrigger, "/game-get", {
  get: {
    responses: { '200': { description: 'The response from the Azure Function' } }
  }
})

License

MIT