刚接触c#，怎么写接口参数注释？

Question

刚接触c#，怎么用注释参数？

/// <summary>
        /// 测试
        /// </summary>
        /// <returns></returns>
        /// 
        [HttpPost]
        public async Task<ReturnMode> Test()
        {
            return ReturnMode.Success();
        }

Answer 1

注释参数本质上是使用的 C# 的文档注释，所以需要在项目里配置通过注释生成文档。右键点击项目名称，在属性里配置（VS2022 + NET6/7 为例）

配置了输出文档文件之后，修改 services.AddSwaggerGen 的配置，

builder.Services.AddSwaggerGen(options =>
{
    var xmlPath = Path.Combine(builder.Environment.ContentRootPath, "WebApplication1.xml");
    options.IncludeXmlComments(xmlPath);
});

其他配置该怎么配就怎么配，关键是这里要 IncludeXmlComments()。因为上面是配置输出到启动目录的，所以其位置在环境提供的 ContentRootPath 目录下。如果是默认的，会输出到 AppContext.BaseDirectory 目录下。

Controller 的文档注释示例及说明

using Microsoft.AspNetCore.Mvc;

namespace WebApplication1.Controllers;

[Route("api/[controller]")]
[ApiController]
public class SampleController : ControllerBase {
    /// <summary>
    /// 这是一个没有参数的 GET 示例
    /// </summary>
    /// <remarks>
    /// 可以在 `&lt;remark&gt;` 标签里写 Markdown。这是 Swagger 解析渲染的。
    /// 但是注意 `&lt;` 和 `&gt;` 要用 `&amp;lt;` 和 `&amp;gt;` 来书写，
    /// 因为 C# 的文档注释本质还是 XML，而且输出的也是 XML。
    ///
    /// 如果需要分段，两段之间加一个空行
    ///
    /// &gt; 也可以引用一段文字
    ///
    /// 或者写一段代码
    ///
    /// ```cs
    /// WriteLine("Hello World");
    /// ```
    /// </remarks>
    [HttpGet]
    public void GetNoParameter() { }

    /// <summary>
    /// 路由参数示例
    /// </summary>
    /// <param name="id">
    /// 这是一条记录的 ID，需要指定为 GUID
    /// </param>
    [HttpGet("{id:guid}")]
    public void GetId(Guid id) { }

    /// <summary>
    /// 查询参数示例
    /// </summary>
    /// <param name="page">页码</param>
    /// <param name="pageSize">每页数据条数</param>
    [HttpGet("query")]
    public void Query([FromQuery] int page, [FromQuery] int? pageSize) { }

    /// <summary>
    /// POST Payload 参数示例
    /// </summary>
    /// <param name="pageInfo">分页信息</param>
    [HttpPost()]
    public void Post([FromBody] PageInfo pageInfo) { }

    /// <summary>
    /// 分页信息数据结构
    /// </summary>
    public record PageInfo {
        /// <summary>页码</summary>
        public int Page { get; set; }

        /// <summary>分页大小</summary>
        public int? PageSize { get; set; }
    }
}

输出效果

Answer 2

方法代码上一行打 ///
然后填空就行了