Azure Functions 2.0如何在Swagger UI中默认显示POST请求体示例
解决方案
下面提供两种适配不同组件的可行实现方案:
方案1:基于Aliencube.AzureFunctions.Extensions.OpenApi.Core组件实现
步骤1:调整请求体配置
你当前代码中请求体配置为text/plain类型、string类型,无法直接展示结构化JSON示例,首先根据你的需求定义请求实体类,并添加示例标注:
// 引入命名空间 using Aliencube.AzureFunctions.Extensions.OpenApi.Core.Attributes; using Aliencube.AzureFunctions.Extensions.OpenApi.Core.Interfaces; using Microsoft.OpenApi.Models; public class UserRequest { [OpenApiExample("testuser")] public string Username { get; set; } [OpenApiExample("1")] public string Userid { get; set; } }
如果需要更灵活的多示例配置,可自定义示例类:
public class UserRequestExample : IOpenApiExample<UserRequest> { public UserRequestExample() { Examples = new Dictionary<string, OpenApiExample> { { "默认示例", new OpenApiExample { Summary = "标准请求参数", Value = new UserRequest { Username = "testuser", Userid = "1" } } } }; } public IDictionary<string, OpenApiExample> Examples { get; set; } } // 给实体类关联示例类 [OpenApiExample(typeof(UserRequestExample))] public class UserRequest { public string Username { get; set; } public string Userid { get; set; } }
步骤2:修改函数特性
将原有的OpenApiRequestBody特性替换为以下配置:
[FunctionName("TestFunction")] [OpenApiOperation(operationId: "TestFunction", tags: new[] { "TestFunction" })] // 替换原有请求体配置,指定content-type为application/json,关联实体类 [OpenApiRequestBody(contentType: "application/json", bodyType: typeof(UserRequest), Required = true)] public static async Task<IActionResult> TestFunctionRun( [HttpTrigger(AuthorizationLevel.Anonymous,"post", Route = null)] HttpRequest TestFunctionRequest, ExecutionContext executionContext) { // 函数逻辑不变 }
如果你业务必须保留
text/plain的content-type,可直接在特性中填写示例字符串,无需定义实体类:[OpenApiRequestBody("text/plain", typeof(string), Example = "{\"username\" : \"testuser\",\"userid\" : \"1\"}")]
方案2:基于AzureFunctions.Extensions.Swashbuckle组件实现
步骤1:安装依赖&配置启动项
先安装对应版本的AzureFunctions.Extensions.Swashbuckle包,之后在Startup类中添加Swagger配置:
using Microsoft.Azure.WebJobs; using Microsoft.Azure.WebJobs.Hosting; using Swashbuckle.AspNetCore.SwaggerGen; using AzureFunctions.Extensions.Swashbuckle; using YourNamespace; [assembly: WebJobsStartup(typeof(Startup))] namespace YourNamespace { public class Startup : IWebJobsStartup { public void Configure(IWebJobsBuilder builder) { builder.AddSwashBuckle(Assembly.GetExecutingAssembly(), opts => { // 基础配置根据你的项目调整 }); builder.Services.AddSwaggerGen(c => { // 启用示例过滤器 c.ExampleFilters(); }); // 注册全局示例 builder.Services.AddSwaggerExamplesFromAssemblyOf<UserRequestExample>(); } } }
步骤2:定义实体&示例类
public class UserRequest { public string Username { get; set; } public string Userid { get; set; } } public class UserRequestExample { public static object GetExample() { return new UserRequest { Username = "testuser", Userid = "1" }; } }
步骤3:修改函数特性
[FunctionName("TestFunction")] [SwaggerOperation(OperationId = "TestFunction", Tags = new[] { "TestFunction" })] [SwaggerRequestBody(Type = typeof(UserRequest), Required = true)] [SwaggerRequestExample(typeof(UserRequest), typeof(UserRequestExample))] public static async Task<IActionResult> TestFunctionRun( [HttpTrigger(AuthorizationLevel.Anonymous,"post", Route = null)] HttpRequest TestFunctionRequest, ExecutionContext executionContext) { // 函数逻辑不变 }
内容的提问来源于stack exchange,提问作者prasanthi
相关产品推荐
相关产品推荐

