如何在Swagger登录端点添加输入示例（无需使用模型）

要在不创建模型的前提下给Swagger的登录POST接口添加请求体示例，你可以按以下步骤操作：

1. 修改控制器方法，从请求体接收参数 #

首先调整你的Post方法，使用[FromBody]标记JObject参数来接收请求体内容，同时修正async void的不良实践（改用async Task<IActionResult>，避免异步操作无法被正确追踪）：

using Microsoft.AspNetCore.Mvc;
using Newtonsoft.Json.Linq;

namespace Web.WebApp.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class AuthenticateUserController : ControllerBase
    {
        private readonly IConfiguration _configuration;

        public AuthenticateUserController(IConfiguration configuration)
        {
            _configuration = configuration;
        }

        [HttpPost("Login")]
        public async Task<IActionResult> Post([FromBody] JObject loginData)
        {
            // 安全提取用户名和密码
            string userName = loginData["userName"]?.ToString();
            string password = loginData["password"]?.ToString();

            // 执行登录逻辑
            // ...

            return Ok(new { Status = "Success", Message = "登录成功" });
        }
    }
}

用JObject替代动态类型，能更稳定地解析JSON请求体，避免动态类型的潜在风险。

2. 给Swagger添加请求体示例 #

你可以通过两种方式实现示例展示，选其一即可：

方式一：使用XML注释（简单快捷） #

1. 启用项目XML文档生成：
   右键项目→属性→生成→勾选"XML文档文件"，设置生成路径（如bin\Debug\net6.0\Web.WebApp.xml）。

2. 在Swagger配置中引入XML文件（Program.cs/Startup.cs）：

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "登录API", Version = "v1" });

    // 加载XML注释文件
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
});

3. 给控制器方法添加带示例的XML注释：

/// <summary>
/// 用户登录接口
/// </summary>
/// <param name="loginData">包含用户名和密码的登录信息</param>
/// <requestBody>
/// <code>
/// {
///   "userName": "admin",
///   "password": "123456"
/// }
/// </code>
/// </requestBody>
/// <returns>登录结果</returns>
[HttpPost("Login")]
public async Task<IActionResult> Post([FromBody] JObject loginData)
{
    // 逻辑代码
}

重启项目后，Swagger页面的登录接口会直接显示请求体示例。

方式二：使用自定义Swagger过滤器（更灵活） #

如果需要对示例做个性化控制，可创建自定义IOperationFilter：

1. 定义过滤器类：

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
using System.Reflection;

public class LoginRequestExampleFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        // 定位到登录接口
        var isLoginAction = context.ApiDescription.ActionDescriptor.DisplayName == 
                           "Web.WebApp.Controllers.AuthenticateUserController.Post";

        if (isLoginAction)
        {
            // 构造示例JSON对象
            var exampleObj = new OpenApiObject
            {
                ["userName"] = new OpenApiString("admin"),
                ["password"] = new OpenApiString("123456")
            };

            // 添加到Swagger请求体示例中
            operation.RequestBody.Content["application/json"].Examples.Add("登录示例", new OpenApiExample
            {
                Value = exampleObj,
                Summary = "标准登录请求示例"
            });
        }
    }
}

2. 在Swagger配置中注册过滤器：

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "登录API", Version = "v1" });
    // 注册自定义过滤器
    c.OperationFilter<LoginRequestExampleFilter>();
});

完成后，Swagger的登录接口请求体区域会显示你自定义的示例内容。

内容的提问来源于stack exchange，提问作者Avanish Srivastava