MinimalApi的接口“身份证”：藏在源码里的元数据
其实Swagger能不能显示接口，核心就看MinimalApi有没有给接口办“身份证”——也就是元数据（EndpointMetadata）。我朋友的问题出在哪儿？他写了个MapPost("/api/order", async (OrderDto order) => { ... })，连个Summary（接口描述）都没加，相当于给接口穿了件“隐形衣”，Swagger根本“看不到”它。
我后来翻了MinimalApi的源码才明白：当你用MapGet/MapPost注册接口时，框架会偷偷做一件事——把接口的“基本信息”塞进一个叫EndpointMetadataCollection的容器里。比如你写：
app.MapGet("/api/user/{id}", (int id) => Results.Ok(new UserDto()))
.WithSummary("根据ID获取用户信息")
.WithDescription("需要用户ID作为路径参数，返回用户详细信息")
.Produces(200)
.Produces(404);
这里的WithSummary、Produces这些方法，本质都是在给接口“贴标签”——WithSummary对应EndpointSummaryMetadata（接口摘要），Produces对应ProducesResponseTypeMetadata（响应类型），这些“标签”就是元数据。
我之前做过一个测试：把WithSummary去掉，Swagger里的接口描述立刻变成了空；再把Produces(404)删掉，响应状态码里就没了404提示——这说明Swagger展示的每一个内容，都对应MinimalApi里的某一条元数据。
微软官方文档里也明确说过（链接 rel=”nofollow”）：MinimalApi的元数据是“轻量级”的接口描述机制，用来替代传统MVC里的[ApiController]属性—— 传统接口靠属性“自我介绍”，MinimalApi靠元数据“递名片”。
Swagger的“翻译官”工作：把元数据变成你看到的文档
那Swagger是怎么“读懂”这些元数据的？我翻了Swashbuckle（Swagger的.NET实现）的源码，发现它的核心逻辑全在SwaggerGenerator类的GetEndpoints方法里——简单说就是“遍历→读取→转换”三步。
第一步：Swagger先“扫一遍”所有接口
Swagger启动时，会先调用IApiDescriptionGroupCollectionProvider获取所有注册的Endpoint（也就是你用Map系列方法加的接口）。我朋友的接口之所以没显示，就是因为他的Endpoint连最基础的EndpointNameMetadata（接口名称）都没有，Swagger遍历的时候直接把它“过滤”了——就像你去酒店check-in，没带身份证肯定不让进。
第二步：Swagger“读”元数据的“说明书”
Swagger会对每个Endpoint做一件事：提取元数据并翻译成自己的语言。比如我给接口加了WithSummary("获取用户信息")，源码里对应的是EndpointSummaryMetadata类型，Swagger看到这个元数据，就会把它对应到Swagger文档的description字段里；再比如我用[FromQuery(Name = "userId")]标注了参数，对应的QueryParameterMetadata会告诉Swagger：“这个参数是从URL Query里来的，名字叫userId”。
我之前做过一个实验：给接口加了WithSummary("获取用户订单列表")和Produces(200)，然后重启项目——Swagger里立刻显示了接口描述和响应类型，这就是因为Swagger准确“读”到了这两个元数据。
第三步：把元数据拼成Swagger文档
最后一步更简单：Swagger把收集到的元数据按OpenAPI规范（就是Swagger遵循的规则）拼成JSON文档，再传给前端页面渲染——你看到的接口名称、参数列表、响应示例，全是这个JSON的“翻译版”。
为了让你更清楚元数据和Swagger的对应关系，我整理了一张表格（这些都是我踩坑后 的“高频对应项”）：
| MinimalApi元数据类型 | Swagger展示内容 | 常用添加方式 |
|---|---|---|
| EndpointSummaryMetadata | 接口描述（Swagger里的“Summary”） | .WithSummary(“获取用户信息”) |
| QueryParameterMetadata | 请求参数（Query类型） | [FromQuery(Name = “userId”)] int id |
| ProducesResponseTypeMetadata | 响应状态码与类型（Swagger里的“Responses”） | .Produces(200) |
解决Swagger“瞎眼”的实战技巧：从源码逻辑到踩坑经验
现在你明白原理了，再遇到Swagger不显示接口的问题，按我这三个步骤查，90%能解决：
WithSummary、Produces这些方法——如果没有，先补上，这是最基础的“入门券”； endpoint.Metadata调试（比如在Program.cs里加app.MapGet("/debug", (IEnumerable endpoints) => endpoints.Select(e => e.Metadata))），看看元数据是不是真的被注册了； AddSwaggerGen里加c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" })，或者有没有UseSwaggerUI启用前端页面。我朋友后来按这个步骤改了代码：给接口加了WithSummary和Produces，再重启项目——Swagger里立刻显示了接口，他拍着大腿说：“原来之前是我没给接口‘办身份证’啊！”
其实MinimalApi和Swagger的“对话”逻辑一点都不复杂，核心就是“MinimalApi给接口贴标签，Swagger读标签做翻译”。你今天可以试试改个接口的WithSummary，或者加个Produces，然后看Swagger的变化——如果成了，记得在评论区告诉我；如果没成，我帮你再揪揪问题在哪儿。
最后提醒一句：元数据不用加太多，够用就行——比如接口描述写清楚用途，响应类型标明白返回什么，参数说明写清楚格式，这些就够Swagger“认识”你的接口了。毕竟Swagger是给人看的，不是给机器看的，简单清晰比“全而杂”更重要。
MinimalApi接口没显示在Swagger里，最常见的原因是什么？
最常见的就是没给接口加“元数据”——比如没用到WithSummary（接口描述）、Produces（响应类型）这些方法。就像你去酒店没带身份证，Swagger根本“认不出”这个接口。我朋友之前写接口只写了MapPost，连个Summary都没有，结果Swagger里完全看不到，后来补上就好了。
元数据是MinimalApi给接口的“身份证”，Swagger得靠这些信息才能把接口展示出来，没加的话相当于接口穿了隐形衣，Swagger自然看不到。
MinimalApi里的WithSummary、Produces这些方法到底是干啥的？
这些方法其实是给接口“贴标签”——也就是加元数据。比如WithSummary是告诉Swagger“这个接口是干啥的”，Produces是说“这个接口成功会返回什么类型的数据”。
举个例子，你给接口加了WithSummary(“根据ID获取用户信息”)，Swagger看到这个元数据，就会把这句话显示在接口描述里；加了Produces(200)，Swagger就知道成功返回的是UserDto类型——这些标签就是Swagger“读懂”接口的关键。
Swagger是怎么把MinimalApi的信息变成我看到的文档的？
其实分三步：首先Swagger会先“扫一遍”所有注册的MinimalApi接口；然后针对每个接口，“读”它的元数据（比如WithSummary、Produces这些加的信息），把这些元数据翻译成Swagger能理解的格式；最后把这些信息拼成符合OpenAPI规范的JSON文档，传给前端页面渲染——你看到的接口名称、参数列表、响应示例，都是从这个JSON来的。
怎么确认MinimalApi的元数据有没有正确注册上？
可以加个调试接口试试。比如在Program.cs里写个MapGet(“/debug”, (IEnumerable endpoints) => endpoints.Select(e => e.Metadata))，然后调用这个接口，就能拿到所有接口的元数据。
如果你的接口加了WithSummary，看返回的Metadata里有没有EndpointSummaryMetadata类型；加了Produces，有没有ProducesResponseTypeMetadata——有的话就是注册成功了，没有的话就得检查代码是不是漏加了。
MinimalApi的元数据是不是加得越多越好？
不是哦，够用就行。比如接口描述写清楚用途，响应类型标明白返回什么，参数说明写清楚格式，这些关键信息加上就够Swagger“认识”你的接口了。
加太多反而容易乱，毕竟Swagger文档是给人看的，简单清晰比“全而杂”更重要——我之前试过加了一堆无关的元数据，结果Swagger里的接口信息反而显得臃肿，后来删掉多余的，反而更清楚。
