本文源码下载地址：http://www.80cxy.com/Blog/ResourceView?arId=202403191532545995NAAqJh

系列教程地址：http://www.80cxy.com/Blog/ArticleView?arId=202403191517574161ay3s5V

本文记录如何给Swagger配置接口描述信息及接口版本控制，实现效果图如下：

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using SignUp.Common.Enum;

namespace SignUp.Common.JWT
{
    public static class SwaggerExtension
    {
        /// <summary>
        /// 接口描述说明
        /// </summary>
        /// <param name="services"></param>
        public static void AddSwaggerExtension(this IServiceCollection services)
        {
            services.AddEndpointsApiExplorer();
            services.AddSwaggerGen(option =>
            {
                #region SwaggerGen版本控制
                typeof(ApiVersions).GetEnumNames().ToList().ForEach(version =>
                {
                    option.SwaggerDoc(version, new Microsoft.OpenApi.Models.OpenApiInfo()
                    {
                        Title = $"极点招聘报名系统后台接口",
                        Version = version,
                        Description = $"接口描述{version}"
                    });
                });
                #endregion

                #region 添加SwaggerGen注释
                // 使用反射获取xml文件，并构造出文件的路径
                //var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlFile = "SignUp.WebApi.xml";

                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                // 启用xml注释，该方法第二个参数启用控制器的注释，默认为false。
                option.IncludeXmlComments(xmlPath, true);
                //对action的名称进行排序，如果有多个，就可以看见效果了。
                option.OrderActionsBy(o => o.RelativePath);
                #endregion
            });
        }
        /// <summary>
        /// 接口版本控制
        /// </summary>
        /// <param name="app"></param>
        public static void UseSwaggerExtension(this WebApplication app)
        {
            app.UseSwagger();
            app.UseSwaggerUI(c => {
                foreach (string version in typeof(ApiVersions).GetEnumNames())
                {
                    c.SwaggerEndpoint($"/swagger/{version}/swagger.json", $"极点招聘报名系统后台接口第【{version}】版本");
                }
            });
        }
    }
}

这时候需要用到XML文档，因为它是通过XML来维护Swagger文档的一些信息。双击项目名称，进入如下配置页面

在项目配置文件中增加如下配置代码

//Swagger版本控制、接口描述配置
services.AddSwaggerExtension();

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using SignUp.Common.ASPNETCore;
using SignUp.Common.Commons;
using SignUp.Common.Enum;
using SignUp.Common.Filter;
using SignUp.Domain.Service;
using SignUp.Infrastructure;
using SignUp.WebApi.ViewModels.Login;
using System.Security.Claims;

namespace SignUp.WebApi.Controllers
{
    /// <summary>
    /// 系统管理相关接口
    /// </summary>
    [Route("api/[controller]/[action]")]
    [ApiExplorerSettings(IgnoreApi = false, GroupName = nameof(ApiVersions.V1))]
    [ApiController]
    public class AdminLoginController : ControllerBase
    {
        private readonly ISystemDomainService _systemDomainService;

        public AdminLoginController(ISystemDomainService systemDomainService)
        {
            _systemDomainService = systemDomainService;
        }
        /// <summary>
        /// 管理用户登录
        /// </summary>
        /// <remarks>
        /// 描述：通过用户名及用户密码登录系统
        /// </remarks>
        /// <param name="req">接口参数</param>
        /// <returns></returns>
        /// <exception cref="ApplicationException"></exception>
        [HttpPost]
        [AllowAnonymous]
        [UnitOfWork(typeof(SignUpDbContext))]
        public async Task<ActionResult> AdminLogin(LoginRequest req)
        {
            return new JsonResult(await _systemDomainService.AdminLogin(req.UserName, req.Password));
        }
    }
}

在Progarm.cs文件增加如下配置代码：

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwaggerExtension();
}

附笔者学习 .net core开发时参考相关项目实例源码：asp.net core webapi项目实例源代码锦集下载（72个）