.net8系列-03图文并茂手把手教你配置Swagger以及实现接口版本控制

前情提要

接上篇文章，我们的应用已经创建完毕了，接口也有了，接下来我们配置显示接口注释和实现接口的版本控制

准备工作

页面展示

在创建项目的时候我们已经有了一个基础版本的Swagger，可以看到接口以及测试接口，如下图

代码展示

配置Swagger实现展示注释

添加代码注释

我们在CommonInfoController.cs文件内接口上方打三个斜线，就会自动出现注释的模板，我们把对应接口的注释写进去，这里我写了几个测试的接口注释，代码如下

using Microsoft.AspNetCore.Mvc;
using static System.Runtime.InteropServices.JavaScript.JSType;
using System;
using System.Reflection;

namespace xiaojinWebApplication.Controllers
{
    [ApiController]
    [Route("[controller]")]
    public class CommonInfoController : ControllerBase
    {

        private readonly ILogger<CommonInfoController> _logger;

        public CommonInfoController(ILogger<CommonInfoController> logger)
        {
            _logger = logger;
        }


        /// <summary>
        /// 测试接口01
        /// </summary>
        /// <returns></returns>
        [HttpGet(Name = "getCommonInfo")]
        public CommonInfo getCommonInfo()
        {
            return new CommonInfo
            {
                Date = DateOnly.FromDateTime(DateTime.Now),
                Text = "getCommonInfo"
            };
        }
        /// <summary>
        /// 测试接口02
        /// </summary>
        /// <param name="userId"></param>
        /// <returns></returns>
        [HttpGet]
        [Route("{userId}")] // 特性路由
        public CommonInfo getCommonInfoTest(int userId)
        {
            return new CommonInfo
            {
                Date = DateOnly.FromDateTime(DateTime.Now),
                Text = "特性路由 userId:" + userId
            };
        }
        /// <summary>
        /// 测试接口03
        /// </summary>
        /// <returns></returns>
        [HttpPost(Name = "postCommonInfo")]
        public CommonInfo postCommonInfo()
        {
            return new CommonInfo
            {
                Date = DateOnly.FromDateTime(DateTime.Now),
                Text = "postCommonInfo"
            };
        }
        /// <summary>
        /// 测试接口04
        /// </summary>
        /// <returns></returns>
        [HttpPut(Name = "putCommonInfo")]
        public CommonInfo putCommonInfo()
        {
            return new CommonInfo
            {
                Date = DateOnly.FromDateTime(DateTime.Now),
                Text = "putCommonInfo"
            };
        }
        /// <summary>
        /// 测试接口05
        /// </summary>
        /// <returns></returns>
        [HttpDelete(Name = "deleteCommonInfo")]
        public CommonInfo deleteCommonInfo()
        {
            return new CommonInfo
            {
                Date = DateOnly.FromDateTime(DateTime.Now),
                Text = "deleteCommonInfo"
            };
        }
    }
}

生成注释配置文件

步骤：右键项目-属性-生成-输出-文档文件打钩

重新build项目

\xiaojinWebApplication\bin\Debug\net8.0文件夹下会出现一个新的文件

添加配置Swagger代码

   builder.Services.AddSwaggerGen(option =>
   {  // Swagger 注释功能
       string basePath = AppContext.BaseDirectory; // 获取应用程序所在目录（绝对路径）
       string xmlPath = Path.Combine(basePath, "xiaojinWebApplication.xml");
       option.IncludeXmlComments(xmlPath);
   });

测试配置

重启项目，Swagger成功展示注释

Swagger版本控制

新增V2，V3版本测试Controllers

创建新版本Controllers，更改注释和返回值作为版本对照

rebuild

手动新增扩展类库

类库添加成功

创建ApiVersionInfo类

namespace xiaojinWebApplication.WebCore
{
    /// <summary>
    /// 版本类
    /// </summary>
    public static class ApiVersionInfo
    {
        public static string V1;
        public static string V2;
        public static string V3;
    }
}

添加版本控制代码

     builder.Services.AddSwaggerGen(option =>
     {  
         // Swagger 注释功能 --- start
         {
             string basePath = AppContext.BaseDirectory; // 获取应用程序所在目录（绝对路径）
             string xmlPath = Path.Combine(basePath, "xiaojinWebApplication.xml");
             option.IncludeXmlComments(xmlPath);
         }
         // Swagger 注释功能 --- end
         // Swagger 版本功能 --- start
         {
             foreach(FieldInfo field in typeof(ApiVersionInfo).GetFields()) 
             {
                 option.SwaggerDoc(field.Name, new Microsoft.OpenApi.Models.OpenApiInfo()
                 {
                     Title = $"{field.Name}:xiaojin WebAPI.",
                     Version = field.Name,
                     Description = $"WebApi {field.Name} 版本"
                 });
                 ;
             }
         }
         // Swagger 版本功能 --- end
     }

     );

UseSwaggerUI代码配置

 app.UseSwaggerUI(option => 
 {
     foreach (FieldInfo field in typeof(ApiVersionInfo).GetFields())
     {
         option.SwaggerEndpoint($"/swagger/{field.Name}/swagger.json", $"{field.Name}");
     }
 }
 );

Controllers代码配置

    [ApiExplorerSettings(GroupName = nameof(ApiVersionInfo.V2))]

注意事项

运行测试

结语

• 今天就写到这里啦~
• 小伙伴们，(￣ω￣(￣ω￣〃 (￣ω￣〃)ゝ我们明天再见啦~~
• 大家要天天开心哦

欢迎大家指出文章需要改正之处~
学无止境，合作共赢

欢迎路过的小哥哥小姐姐们提出更好的意见哇~~