【个人博客搭建】（6）搭建swagger文档

news2025/2/25 21:19:25

1、前言：

其实在创建webapi时我们就已经选择了swagger了。

也就是代码

app.UseSwagger();
app.UseSwaggerUI();

但是我们可以对其进行拓展，补充信息。

像常需要的action接口中文信息，Controller控制器中文信息等...

进入正题。

2、添加版本枚举

/// <summary>
/// Api接口版本 自定义 （一般有一个就够了）
/// ps：注意用小写
/// </summary>
public enum ApiVersions
{
    /// <summary>
    /// V1 版本
    /// </summary>
    v1 = 1,

    /// <summary>
    /// V2 版本
    /// </summary>
    v2 = 2,
}

3、注入服务：（已踩坑）

builder.Services.AddSwaggerGen(c =>
{
    typeof(SwaggerDocSettings.ApiVersions).GetEnumNames().ToList().ForEach(version =>
    {
        c.SwaggerDoc(version,
            new OpenApiInfo
                    {
                        Title = "Plateau-Poetize " + version,
                        Version = version,
                        Description = "根据开源项目Poetize编写Net版本WebApi。",
                        Contact = new OpenApiContact { Name = "Contact：Plateau", Url = new Uri("https://gitee.com/HelloAspNet") },
                        License = new OpenApiLicense { Name = "License：Plateau", Url = new Uri("https://gitee.com/HelloAspNet") },
                    });
                c.OrderActionsBy(o => o.RelativePath);
            });

    // 设置API注释文档生成器
    var apiname = Assembly.GetExecutingAssembly().GetName().Name;
    var xmlFile1 = apiname + ".xml";
    var xmlPath1 = Path.Combine(AppContext.BaseDirectory, xmlFile1);

    //默认的第二个参数是false，这个是controller的注释，记得修改。
    //（PS：这里路径没文件会报错的。如果把Api的项目文件节点加上<GenerateDocumentationFile>true</GenerateDocumentationFile>就不会了）
    c.IncludeXmlComments(xmlPath1, true);
});

4、版本选择项目。（我这不做循环处理了）

app.UseSwaggerUI(c =>
{
    //左上角的下拉框（默认不配置就只有一个）
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "BlogWebApi v1");
    c.SwaggerEndpoint("/swagger/v2/swagger.json", "My API v2");
});

5、添加路由特性。

5.1、按原生版应该走。

[ApiVersion("1")]
[Route("api/v{version:apiVersion}/[controller]/[action]")]

但是报错，补充

builder.Services.AddRouting(options =>
{
    options.ConstraintMap.Add("apiVersion", typeof(ApiVersionRouteConstraint));

});

还是不行，需要实现了'IParameterPolicy'接口。

后续换了中方式，查看别人的代码实现。新增特性去实现

5.2、创建类，设置特性。

这里主要是为了实现右上角版本选择后实现显示不同版本接口问题。之前的方式会带入一个版本的参数，或者不管如何选，后会有所有接口信息列表

 /// <summary>
 /// 自定义路由 /api/{version}/[controler]/[action]
 /// swagger版本
 /// </summary>
 [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true, Inherited = true)]
 public class ApiVersionCustomRouteAttribute : RouteAttribute, IApiDescriptionGroupNameProvider
 {

     /// <summary>
     /// 分组名称,是来实现接口 IApiDescriptionGroupNameProvider
     /// </summary>
     public string GroupName { get; set; }


     /// <summary>
     /// 常用方式
     /// </summary>
     /// <param name="version"></param>
     /// <param name="actionName"></param>
     public ApiVersionCustomRouteAttribute(SwaggerDocSettings.ApiVersions version, string actionName = "")
         : base($"/BlogApi/{version.ToString()}/[controller]/[action]")
     {
         GroupName = version.ToString();
     }


     /// <summary>
     /// 可自定义action的
     /// </summary>
     /// <param name="actionName"></param>
     /// <param name="version"></param>
     public ApiVersionCustomRouteAttribute(string actionName, SwaggerDocSettings.ApiVersions version)
         : base($"/BlogApi/{version.ToString()}/[controller]/{actionName}")
     {
         GroupName = version.ToString();
     }
 }

5.3、添加特性。这个必须要有一个加在Controller上边，然后具体的方法可加也可不加。

[ApiVersionCustomRoute(SwaggerDocSettings.ApiVersions.v1)]

5.4、测试

 /// <summary>
 /// 测试连接1
 /// </summary>
 /// <param name="t">字符串</param>
 /// <returns></returns>
 [HttpGet]
 [ApiVersionCustomRoute(SwaggerDocSettings.ApiVersions.v1)]
 public string Test(string t)
 {
     return "【Test】OK.输入的是：" + t;
 }
 /// <summary>
 /// 测试连接2
 /// </summary>
 /// <param name="t">字符串</param>
 /// <returns></returns>
 [HttpGet]
 [ApiVersionCustomRoute("GetTest",SwaggerDocSettings.ApiVersions.v1)]
 public string TestGet(string t)
 {
     return "【Test】OK.输入的是：" + t;
 }

 /// <summary>
 /// 测试连接3
 /// </summary>
 /// <param name="t">字符串</param>
 /// <returns></returns>
 [HttpGet]
 [ApiVersionCustomRoute(SwaggerDocSettings.ApiVersions.v2)]
 public string Test2(string t)
 {
     return "【Test2】OK.输入的是：" + t;
 }

运行效果：

V1：