c# - 如何在Azure Function中配置OpenApiRequestBody？

Question

我想用 OpenApi 注释来装饰我的 azure c# 函数。该函数接受 JSON 模式作为参数。如何在注释中提及这一点。

想知道如何配置下面的注释

[OpenApiRequestBody(contentType: "json", bodyType: typeof(System.Text.Json.JsonDocument), Description = "Parameters",示例 =typeof(Parameters))]

public class ModifyOrder
    {
        [FunctionName("ModifyOrder")]
        [OpenApiOperation(operationId: "run", tags: new[] { "Modify Order" })]
        [OpenApiSecurity("function_key", SecuritySchemeType.ApiKey, Name = "code", In = OpenApiSecurityLocationType.Query)]
        [OpenApiRequestBody(contentType: "json", bodyType: typeof(System.Text.Json.JsonDocument), Description = "Parameters",Example =typeof(Parameters))]
        [OpenApiResponseWithBody(statusCode: HttpStatusCode.OK, contentType: "text/plain", bodyType: typeof(string), Description = "The OK response")]
        public static async Task<IActionResult> run(
            [HttpTrigger(AuthorizationLevel.Function, "put", Route = null )] HttpRequest req,
            ILogger log)
        {
            log.LogInformation($"C# HTTP trigger function processed a request.");

            string ordernumber;

            string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
            dynamic data = JsonConvert.DeserializeObject(requestBody);
            ordernumber = data?.orderno;

            string responseMessage = $"Order:{ordernumber}";
            return new OkObjectResult(responseMessage);
        }

    }

    [OpenApiExample(typeof(Parameters))]
    public class Parameters 
    {
        /// <summary>The id of the customer in the context. This is also called payer, sub_account_id.</summary>
        [Newtonsoft.Json.JsonProperty("customerId", Required = Newtonsoft.Json.Required.Always)]
        [System.ComponentModel.DataAnnotations.Required(AllowEmptyStrings = true)]
        public string CustomerId { get; set; }
        /// <summary>The order number. Used to uniquely identify a group of order lines.</summary>
        [Newtonsoft.Json.JsonProperty("orderNumber", Required = Newtonsoft.Json.Required.Always)]
        [System.ComponentModel.DataAnnotations.Required(AllowEmptyStrings = true)]
        public string OrderNumber { get; set; }
    }

Answer 1

OpenApiRequestBody主要参数在你的例子中要关注的是 bodyType 。参数Example此处可以省略并以不同的方式配置(稍后解释)。而不是使用 JsonDocument而是使用您的 Parameters bodyType 的类(class)- 这将暴露 Parameters 的特征Swagger 定义中的类。

您不能使用Parameters类本身代表一个有效的示例，而应该创建一个继承 OpenApiExample<T> 的专用类或者在你的情况下OpenApiExample<Parameters>然后在这个类中覆盖 Build构造 Parameters 示例实例的方法。然后，您可以通过使用属性 [OpenApiExample<T>] 修饰Parameters 类来公开您的示例。 (正如您所做的那样，但使​​用示例类类型!)。

关于 OpenApiRequestBody 一些值得注意的事情更一般地说，这个库是 Description OpenApiRequestBody的属性(property)当前未按预期工作；描述文本未在 Swagger 中呈现 requestBody定义。这引出了我的下一点，即(在撰写本文时)这个库 - Microsoft.Azure.WebJobs.Extensions.OpenApi - 处于预发布状态(0.7.2 )，因此，正如我自己发现的那样，似乎确实包含一些错误。

我修改了你的ModifyOrder下面的类；我希望这个版本能够帮助回答您的问题!

public static class ModifyOrder
{
    [FunctionName("ModifyOrder")]
    [OpenApiOperation(operationId: "run", tags: new[] { "Modify Order" })]
    [OpenApiSecurity("function_key", SecuritySchemeType.ApiKey, Name = "code", In = OpenApiSecurityLocationType.Query)]
    [OpenApiRequestBody(contentType: "application/json", bodyType: typeof(Parameters), Description = "Parameters", Required = true)]
    [OpenApiResponseWithBody(statusCode: HttpStatusCode.OK, contentType: "text/plain", bodyType: typeof(string), Description = "The OK response")]
    public static async Task<IActionResult> run(
        [HttpTrigger(AuthorizationLevel.Function, "PUT", Route = null)] HttpRequest req,
        ILogger log)
    {
        log.LogInformation($"C# HTTP trigger function processed a request.");

        string ordernumber;

        string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
        dynamic data = JsonConvert.DeserializeObject(requestBody);
        ordernumber = data?.orderno;

        string responseMessage = $"Order:{ordernumber}";
        return new OkObjectResult(responseMessage);
    }
}

[OpenApiExample(typeof(ParametersExample))]
public class Parameters
{
    /// <summary>The id of the customer in the context. This is also called payer, sub_account_id.</summary>
    [OpenApiPropertyDescription("The id of the customer in the context. This is also called payer, sub_account_id.")]
    [Newtonsoft.Json.JsonProperty("customerId", Required = Newtonsoft.Json.Required.Always)]
    [System.ComponentModel.DataAnnotations.Required(AllowEmptyStrings = true)]
    public string CustomerId { get; set; }

    /// <summary>The order number. Used to uniquely identify a group of order lines.</summary>
    [OpenApiPropertyDescription("The order number. Used to uniquely identify a group of order lines.")]
    [Newtonsoft.Json.JsonProperty("orderNumber", Required = Newtonsoft.Json.Required.Always)]
    [System.ComponentModel.DataAnnotations.Required(AllowEmptyStrings = true)]
    public string OrderNumber { get; set; }
}

public class ParametersExample : OpenApiExample<Parameters>
{
    public override IOpenApiExample<Parameters> Build(NamingStrategy namingStrategy = null)
    {
        this.Examples.Add(
            OpenApiExampleResolver.Resolve(
                "ParametersExample",
                new Parameters()
                {
                    CustomerId = "CUST12345",
                    OrderNumber = "ORD001"
                },
                namingStrategy
            ));

        return this;
    }
}