Azure 功能描述到 APIM 描述

Question

当您将函数导入 APIM 时，是否可以向导入到 APIM API 描述中的 Azure 函数添加描述？

Answer 1

是的，可以通过导入 Azure API 管理 (APIM) API 描述的方式向 Azure 函数添加描述。这涉及将文档注释直接添加到您的 Azure Function 代码中，然后 APIM 在导入过程中识别这些注释。

以下是实现此目的的一般方法：

1. 将 XML 注释添加到您的 Azure 函数代码:

   • 在 Azure 函数中，您可以在函数定义上方添加 XML 文档注释。这与记录任何 C# 方法的方式类似。例如：

     /// <summary>
     /// This is a sample Azure Function that does XYZ.
     /// </summary>
     /// <param name="req">HTTP request parameter.</param>
     /// <returns>A task that represents the asynchronous operation.</returns>
     [FunctionName("SampleFunction")]
     public static async Task<IActionResult> Run(
         [HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = null)] HttpRequest req,
         ILogger log)
     {
         // Function code goes here
     }
     

   • 这些注释用于生成 XML 文档文件。

2. 启用 XML 文档文件生成:

   • 在您的 Azure Functions 项目中，您需要启用 XML 文档文件的生成。这通常是通过添加以下内容在项目文件 (

     .csproj

     ) 中完成的：

     <PropertyGroup>
         <GenerateDocumentationFile>true</GenerateDocumentationFile>
         <NoWarn>$(NoWarn);1591</NoWarn>
     </PropertyGroup>
     

   • 此步骤可确保将 XML 注释编译为可供 APIM 等工具使用的 XML 文件。

3. 将Function App导入APIM:

   • 将 Azure Function App 导入 Azure API 管理时，请确保 APIM 可以访问 XML 文档文件。导入过程应识别此文件中的描述并将其包含在 APIM 的 API 定义中。

4. 审核并发布：

   • 导入后，检查 APIM 中的 API 定义，以确保正确导入描述和其他文档注释。您可能需要根据 APIM 中的显示方式调整格式或内容。

5. 定期更新:

   • 如果您对 Azure Function 代码中的描述进行更改，请记住更新 APIM 中的 API 文档。

通过执行这些步骤，您可以在 Azure API 管理中拥有更具描述性和记录的 API，反映 Azure 函数代码中提供的详细信息。这种方法为内部和外部消费者增强了 API 的可维护性和可用性。

希望这有帮助！如果确实如此，请随意竖起大拇指 - 它也可以帮助社区中的其他人！