当前位置：首页 > news >正文

.Net6 Api Swagger配置

news 来源：原创 2024/4/29 3:12:44

1、定义个Swagger版本（组）的枚举

namespace WebApp.Enums
{/// <summary>/// api版本枚举/// </summary>public enum ApiVersion{/// <summary>/// v1版本/// </summary>v1 = 1,/// <summary>/// v2版本/// </summary>v2 = 2,}
}

2、添加IServiceCollection 扩展类，配置SwaggerDoc

using Microsoft.OpenApi.Models;
using WebApp.Enums;namespace WebApp.Common.Swagger
{/// <summary>/// SwaggerDoc配置/// </summary>public static class SwaggerExtension{/// <summary>/// Swagger启动服务/// </summary>/// <param name="services">容器</param>/// <param name="apiAssemblyName">项目名称：可以通过Assembly.GetExecutingAssembly().GetName().Name获取</param>/// <param name="apiTitle">api的标题</param>/// <param name="description">api的描述</param>public static void AddSwaggerSetup(this IServiceCollection services, string? apiAssemblyName, string apiTitle, string description){if (services == null) throw new ArgumentNullException(nameof(services));#region 添加Swaggerservices.AddSwaggerGen(options =>{//options.SwaggerDoc("v1", new OpenApiInfo { Title = "售楼API", Version = "v1" });typeof(ApiVersion).GetEnumNames().ToList().ForEach(version =>{options.SwaggerDoc(version, new OpenApiInfo(){Version = version,Title = $"{apiTitle}",Description = $"{description} {version}",//Contact = new OpenApiContact//{//    Name = "潇湘夜雨",//    Email ="123@qq.com"//}});});// 获取当前项目的 XML文档文件路径：比如我的项目名称叫WebApp，那么它默认的 XML文档文件路径就是当前项目下的 WebApp.xmlvar xmlFile = $"{apiAssemblyName}.xml";var xmlFileFullPath = Path.Combine(AppContext.BaseDirectory, xmlFile);//var domainXmlPath = Path.Combine(AppContext.BaseDirectory, "Bgy.Domain.xml");      // 获取Bgy.Domain.xml文件路径//var viewmodelXmlPath = Path.Combine(AppContext.BaseDirectory, "Bgy.ViewModel.xml");// 获取Bgy.ViewModel.xml文件路径options.IncludeXmlComments(xmlFileFullPath, true); // 添加控制器层注释，true表示显示控制器注释//options.IncludeXmlComments(domainXmlPath);       // 添加Domain层注释//options.IncludeXmlComments(viewmodelXmlPath);    // 添加ViewModel层注释//添加一个必须的全局安全信息，//第一个参数是方案唯一名称：和AddSecurityDefinition方法指定的方案名称标识一致即可：BearerAuth//第二个参数是方案的描述：可以是BasicAuthScheme、ApiKeyScheme的实例或OAuth2Schemeoptions.AddSecurityDefinition("BearerAuth", new OpenApiSecurityScheme(){Description = "在下框中输入请求头中需要添加Jwt授权Token：Bearer Token",Name = "Authorization",In = ParameterLocation.Header, //配置jwt默认加在Authorization信息的位置：这里配置的是将jwt信息放在请求头Header中            Type = SecuritySchemeType.Http,//使用Authorize头部                  Scheme = "bearer", //内容为以 bearer开头BearerFormat = "JWT",//Reference= new OpenApiReference() { Type = ReferenceType.SecurityScheme, Id = "bearerAuth" }});//注册全局认证（所有的接口都可以使用认证）options.AddSecurityRequirement(new OpenApiSecurityRequirement(){{new OpenApiSecurityScheme{Reference = new OpenApiReference{Type = ReferenceType.SecurityScheme,Id = "BearerAuth" //方案名称标识}},new string[] {} //不设权限}});});#endregion}}
}

3、appsettings.json配置文件

{"Logging": {"LogLevel": {"Default": "Information","Microsoft.AspNetCore": "Warning"}},"AllowedHosts": "*","Swagger": {"environmentVariables": "development" //:development  :testing  :production}
}

4、在Program.cs中注册SwaggerDoc及启用SwaggerUI

using System.Reflection;
using WebApp.Common.Swagger;
using WebApp.Enums;var builder = WebApplication.CreateBuilder(args);// Add services to the container.builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();//并注册Swagger服务并配置文档信息。
//builder.Services.AddSwaggerGen();
builder.Services.AddSwaggerSetup(Assembly.GetExecutingAssembly().GetName().Name, "凤凰网", "凤凰网系统接口服务  版本:");var app = builder.Build();// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{app.UseSwagger();//app.UseSwaggerUI();
}
var enviroment = app.Configuration["Swagger:environmentVariables"];
switch (enviroment)
{case "development":app.UseSwagger();//启用Swagger中间件//配置版本app.UseSwaggerUI(options =>{typeof(ApiVersion).GetEnumNames().ToList().ForEach(version =>{options.SwaggerEndpoint($"/swagger/{version}/swagger.json", version);});});break;case "testing":app.UseSwagger();app.UseSwaggerUI(options =>{typeof(ApiVersion).GetEnumNames().ToList().ForEach(version =>{options.SwaggerEndpoint($"/swagger/{version}/swagger.json", version);});});break;case "production":break;}app.UseAuthorization();app.MapControllers();app.Run();

5、Api接口中使用

在接口控制器，或者方法上添加版本（组）标识：[ApiExplorerSettings(GroupName = "v1")]

using Microsoft.AspNetCore.Mvc;
using WebApp.Enums;namespace WebApp.Controllers
{/// <summary>/// 测试接口/// </summary>[ApiController]//[ApiController]能够推断参数的绑定源,就不需要[FromBody][FromForm][FromHeader][FromQuery][FromRoute]....来主动指定接收参数的形式[Route("api/[controller]/[action]")]public class WeatherForecastController : ControllerBase{private readonly ILogger<WeatherForecastController> _logger;/// <summary>/// 构造函数/// </summary>/// <param name="logger"></param>public WeatherForecastController(ILogger<WeatherForecastController> logger){_logger = logger;}/// <summary>/// 查询案列1/// </summary>/// <param name="id">编号</param>/// <returns></returns>[HttpGet("Abc")] //url地址是：api/WeatherForecast/Get/Abc[ApiExplorerSettings(GroupName = "v1")] //可以将版本放到控制器上public IActionResult Get(int id){return Ok(id);//返回值：IActionResult//return NotFound(); 404//return Redirect("/Home/Index");//var content = "Hello, World!";//return Content(content, "text/plain");//var data = new { Name = "John", Age = 30 };//return Json(data);//var filePath = "/path/to/file.pdf";//return File(filePath, "application/pdf", "filename.pdf");//byte[] videoBytes = System.IO.File.ReadAllBytes(containerPath);//return File(videoBytes, "video/mp4");}/// <summary>/// 查询案列2：路由的伪静态/// </summary>/// <param name="name"></param>/// <returns></returns>[HttpGet("Abc/{name}")] //url地址是：api/WeatherForecast/Get/Abc/lily   :lily是name值， 同时name值是必填的，{name}必须要与action的参数名称一致。这就是路由的伪静态形式[ApiExplorerSettings(GroupName = nameof(ApiVersion.v2))]public IActionResult Get(string name){return Ok(name);}/// <summary>/// 标记了[NonAction]特性，则不被视为控制器的操作方法/// </summary>/// <param name="id"></param>/// <returns></returns>[HttpPost(Name = "{id}")][NonAction]public string PostTest(int id){return id.ToString();}}
}