.net core使用swagger

Core使⽤Swagger⽣成在线api⽂档参考：整合后调通，上代码：Controller：using Microsoft.AspNetCore.Authorization;using Microsoft.AspNetCore.Mvc;using Microsoft.IdentityModel.Tokens;using System;using System.Collections.Generic;using System.IdentityModel.Tokens.Jwt;using System.Linq;using System.Security.Claims;using System.Text;using System.Threading.Tasks;namespace WebApp1.Controllers{[Route("XxxApi/[controller]")]public class WebApiController : Controller{///<summary>///获取Token///</summary>///<param name="uid">明⽂</param>///<returns>密⽂</returns>[HttpGet, Route("GetToken")]public ActionResult<string> GetToken(string uid){var claims = new List<Claim>{new Claim(JwtRegisteredClaimNames.Nbf,$"{new DateTimeOffset(DateTime.Now).ToUnixTimeSeconds()}"),//⽣效时间new Claim(JwtRegisteredClaimNames.Exp,$"{new DateTimeOffset(DateTime.Now.AddMinutes(30)).ToUnixTimeSeconds()}"),//过期时间new Claim(, uid)};// 密钥var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("SecurityKey123456"));var creds = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);JwtSecurityToken jwt = new JwtSecurityToken(claims: claims,signingCredentials: creds);var handler = new JwtSecurityTokenHandler();// ⽣成 jwt字符串var strJWT = handler.WriteToken(jwt);return Ok(strJWT);}///<summary>///获取⽤户姓名///</summary>///<param name="id">⽤户唯⼀标识id</param>///<returns>⽤户姓名</returns>[HttpGet, Authorize, Route("GetUserName")]public string GetUserName(int id){return"abc";}}}Startup：using db_face.Models;using db_oa.Models;using Microsoft.AspNetCore.Authentication.JwtBearer;using Microsoft.AspNetCore.Builder;using Microsoft.AspNetCore.Hosting;using Microsoft.EntityFrameworkCore;using Microsoft.Extensions.Configuration;using Microsoft.Extensions.DependencyInjection;using Microsoft.Extensions.Hosting;using Microsoft.IdentityModel.Tokens;using Microsoft.OpenApi.Models;using System;using System.IO;using System.Text;namespace WebApp1{public class Startup{public Startup(IConfiguration configuration){Configuration = configuration;}public IConfiguration Configuration { get; }// This method gets called by the runtime. Use this method to add services to the container.public void ConfigureServices(IServiceCollection services){// 使⽤ Authenticationservices.AddAuthentication(s =>{s.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;s.DefaultScheme = JwtBearerDefaults.AuthenticationScheme;s.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;}).AddJwtBearer(options =>{options.TokenValidationParameters = new TokenValidationParameters{ValidateIssuer = false,//是否验证IssuerValidateAudience = false,//是否验证AudienceValidateLifetime = true,//是否验证失效时间ClockSkew = TimeSpan.FromMinutes(1),ValidateIssuerSigningKey = true,//是否验证SecurityKeyIssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("SecurityKey123456"))};});services.AddControllersWithViews();//注册Swagger⽣成器，定义⼀个和多个Swagger ⽂档services.AddSwaggerGen(c =>{c.SwaggerDoc("v1", new OpenApiInfo{Version = "v1",Title = "⽤户信息 API",Description = "这是⼀个查询⽤户信息的 Web API",Contact = new OpenApiContact{Name = "张三",Email = "abc@"}});// 为 Swagger JSON and UI设置xml⽂档注释路径var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);var xmlPath = bine(basePath, "WebApp1.xml");c.IncludeXmlComments(xmlPath);//为 Swagger UI 页⾯顶部加上按钮及填写token的弹框c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme{Description = "授权(数据将在请求头中进⾏传递)直接在下⾯框中输⼊Bearer {token}(注意两者之间是⼀个空格) \"", Name = "Authorization",//jwt默认的参数名称In = ParameterLocation.Header,//jwt默认存放Authorization信息的位置(请求头中)Type = SecuritySchemeType.ApiKey});//为 Swagger UI 页⾯上列出的每个⽅法加⼩锁图标(每个请求都会在head加token)c.AddSecurityRequirement(new OpenApiSecurityRequirement{{new OpenApiSecurityScheme{Reference = new OpenApiReference{Id = "Bearer",Type = ReferenceType.SecurityScheme}},Array.Empty<string>()}});});}// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.public void Configure(IApplicationBuilder app, IWebHostEnvironment env){if (env.IsDevelopment()){eDeveloperExceptionPage();}else{eExceptionHandler("/Home/Error");}eStaticFiles();eRouting();eAuthentication();eAuthorization();eEndpoints(endpoints =>{endpoints.MapControllerRoute(name: "default",pattern: "{controller=Home}/{action=Index}/{id?}");});//启⽤中间件服务⽣成Swagger作为JSON终结点eSwagger();//启⽤中间件服务对swagger-ui，指定Swagger JSON终结点eSwaggerUI(c =>{c.SwaggerEndpoint("/swagger/v1/swagger.json", "API V1");//c.RoutePrefix = string.Empty;});}}}对于不熟的⼈来说还是会遇到⼀些坑的：SecurityKey长度必须16位以上，不然运⾏时会报错。

Core使⽤Swagger实现接⼝⽂档并分组 每⼀个程序员都有重构他⼈代码的冲动，但是，每⼀个程序员都不会有写接⼝⽂档的冲动。

据我所知，在.net项⽬中，很多同⾏的中⼩型项⽬接⼝⽂档都使⽤Swagger，最近⼏个朋友⼀起讨论，有没有⽐较好⽤的类似Swagger 接⼝⽂档开源项⽬，其中有朋友反馈说api太多的情况下，使⽤Swagger⽂档就是⼀个灾难，因为接⼝太多，前端开发⼈员很难找到⾃⼰想要的接⼝，因为所有的接⼝和接⼝实体类都展⽰在⼀个页⾯上。

说实话，我以前还真没有关注过这个问题，这两天我有个项⽬，接⼝也⽐较多，⾃⼰在测试接⼝的时候才发现确实存在这种情况。

由于公司内部还有⼀套⾃⼰的接⼝⽂档框架，使⽤体验相对于Swagger更优，所以我就想Swagger怎么就不能像我们⾃⼰的框架那样，将webapi 分组呢。

后来查了些资料，Swagger团队早就为我想到了，结论就是Swagger也⽀持接⼝分组。

⼀般我们分组都是按照控制器来分组，⼀个webapi控制器也就是⼀个模块，具体实现我们往下看：接⼊Swagger1.在NuGet包管理器中安装Swashbuckle.AspNetCore2.添加配置⽂件：swaggergroupconfigs.json，⽂件内容如下：{"swaggergroupconfigs": [{"GroupName": "Web","Title": "Web模块","Version": "V1.0"},{"GroupName": "Order","Title": "订单模块","Version": "V1.0"},{"GroupName": "System","Title": "系统模块","Version": "V1.0"}]}3.加载分组配置⽂件（这⾥使⽤了环境变量）：public static IHostBuilder CreateHostBuilder(string[] args) =>Host.CreateDefaultBuilder(args).ConfigureAppConfiguration((hostBuilderContext, configurationBuilder) =>{var env = hostBuilderContext.HostingEnvironment;//optional：如果是必要的配置⽂件，可选就要设定为false，当⽂件不存在就会引发FileNotFoundException。

.NETCORE配置Swagger⽂档1、先通过NuGet安装Swashbuckle.AspNetCore ，⽀持.NET core,版本是4.0.1，以上版本好像有些功能不⽀持2、startup⽂件⾥注⼊swagger，ConfigureServices ⽅法注⼊swagger内容，#region 添加SwaggerUIservices.AddSwaggerGen(options =>{options.SwaggerDoc("v1", new Info{Title = "钉钉测试⽂档",Version = "v1"});//Determine base path for the application.var basePath = PlatformServices.Default.Application.ApplicationBasePath;//Set the comments path for the swagger json and ui.var xmlPath = bine(basePath, "DingDingTest.xml");options.IncludeXmlComments(xmlPath);});#endregion 以上最坑地⽅是PlatformServices这个类找不到，查了半天资料才知道需要引⼊dll，通过nuget添加程序集，Microsoft.Extensions.PlatformAbstractionsDingDingTest.xml ⽂件通过属性⽣成⾥打钩⾃动⽣成xml⽂件管道⾥增加swagger管道，eSwagger();eSwaggerUI(c =>{c.SwaggerEndpoint("/swagger/v1/swagger.json", "钉钉测试 API V1");});运⾏报错，Fetch errorundefined /swagger/v1/swagger.jsonswagger.JSON是动态⽣成的，⽆法⼿⼯找到，找了半天才发现，有⼀个⽅法我没有设置路由造成⽣成json⽂件报错，不是找不到的问题，所以所有⽅法都要设置路由，不然会报这种莫名的错误地址栏输⼊地址，测试成功，搭建成功，但是每次都要输⼊地址才会出现，现在默认显⽰swagger，修改launchsettings.json⽂件1 {2"iisSettings": {3"windowsAuthentication": false,4"anonymousAuthentication": true,5"iisExpress": {6"applicationUrl": "http://localhost:12569/",7"sslPort": 08 }9 },10"profiles": {11"IIS Express": {12"commandName": "IISExpress", 13"launchBrowser": true,14"launchUrl": "swagger/ui", 15"environmentVariables": { 16"ASPNETCORE_ENVIRONMENT": "Development"17 }18 },19"DataSaas": {20"commandName": "Project", 21"launchBrowser": false,22"launchUrl": "swagger/ui", 23"environmentVariables": { 24"ASPNETCORE_ENVIRONMENT": "Development"25 },26"applicationUrl": "http://localhost:12570/"27 }28 }29 }。

.NetCoreSwagger配置第⼀步，安装swagger使⽤程序包管理器控制台，输⼊如下命令：PM> Install-Package Swashbuckle.AspNetCore -Version 5.0.0-rc4第⼆部，StartUp.cs配置ConfigureServices⽅法中添加如下代码：public void ConfigureServices(IServiceCollection services){services.AddSwaggerGen(m=> {m.SwaggerDoc("SWG1",new OpenApiInfo {Title = "swaggerTest",Version= "SWG1" }); });services.AddControllers();}注意 SWG1 这是随便取的名字Configure中添加如下代码，使⽤中间件：eSwagger();eSwaggerUI(m=>{m.SwaggerEndpoint("/Swagger/SWG1/swagger.json","swaggerTest");});注意这⾥的，SWG1要和上⾯的SWG1名称保存⼀直。

在配置⼀下 launchSettings.json"profiles": {"IIS Express": {"commandName": "IISExpress","launchBrowser": true,"launchUrl": "swagger/index.html","environmentVariables": {"ASPNETCORE_ENVIRONMENT": "Development"}},"WebSwagger": {"commandName": "Project","launchBrowser": true,"launchUrl": "weatherforecast","applicationUrl": "http://localhost:5000","environmentVariables": {"ASPNETCORE_ENVIRONMENT": "Development"}}}运⾏项⽬之后。

.netcore的Swagger接⼝⽂档使⽤教程（⼆）：NSwag 上⼀篇介绍了Swashbuckle ，地址： 讲的东西还挺多，怎奈微软还推荐了⼀个NSwag，那就继续写吧！ 但是和Swashbuckle⼀样，如果还是按照那样写，东西有点多了，所以这⾥就偷个懒吧，和Swashbuckle对照的去写，介绍⼀些常⽤的东西算了，所以建议看完上⼀篇再继续这⾥。

⼀、⼀般⽤法 创建⼀个.net core项⽬（这⾥采⽤的是.net core3.1），然后使⽤nuget安装NSwag.AspNetCore，建议安装最新版本。

同样的，假如有⼀个接⼝： ///<summary>///测试接⼝///</summary>[ApiController][Route("[controller]")]public class HomeController : ControllerBase{///<summary>/// Hello World///</summary>///<returns>输出Hello World</returns>[HttpGet]public string Get(){return"Hello World";}} 接⼝修改Startup，在ConfigureServices和Configure⽅法中添加服务和中间件 public void ConfigureServices(IServiceCollection services){services.AddOpenApiDocument(settings =>{settings.DocumentName = "v1";settings.Version = "v0.0.1";settings.Title = "测试接⼝项⽬";settings.Description = "接⼝⽂档说明";});...}public void Configure(IApplicationBuilder app, IWebHostEnvironment env){ ...eOpenApi();eSwaggerUi3();...} 点击Try it out可以直接调⽤接⼝。

Core的Swagger接⼝根据模块、版本分组近期⼀直在学习 Core，微软的⽂档太难看，都是英⽂翻译过来的，很不友好，感谢这个博客，，让我⼊门了，刚学到这个时，我就有个需求，因为我之前写过的系统是分了不同的模块，模块⾥⾯再分控制器，不同模块经常会有相同名称的控制器，例如销售中⼼模块⾥有个合同管理控制器，采购中⼼模块⾥也有个合同管理控制器，⽽且我⼀个系统接⼝可能得上百个，那如果都在⼀个页⾯显⽰的话，那也太多了，所以我想能不能把接⼝进⾏分组。

在博客系统后⾯也有介绍到，还有⽹上查到的(我发现⽹上关于 Core的资料还是⽐较少)，再结合我⾃⼰的需求修改了⼀下。

先说下我的想法：定义⼀个系统分组枚举Enum，包含我系统所有的控制器分组（或者版本），然后再定义⼀个特性Attribute，可以接收刚才那个Enum值，在需要分组的控制器类上⾯定义特性Attribute，Swagger根据系统分组枚举Enum的值进⾏分组，将特性Attribute的分组枚举值⼀样的归为同⼀个分组，没有加特性Attribute的归在⽆分组下，最终效果如下下⾯是我的代码，理解为主，不⽤完全按我写的基础Swagger的⽤法就不说的，具体可看这个⼤师关于Swagger部分的教程，⾮常适合初级⼊门在项⽬创建⼀个⽬录（ApiGroup），然后创建三个类，分别为ApiGroupAttribute.cs（控制器特性），ApiGroupNames.css（系统分组枚举），GroupInfoAttribute.cs（给系统分组枚举值增加相关信息的特性，这个主要是⽤于在Swagger分组时可关联Title，Version，Description值）ApiGroupAttribute.cs代码如下using Microsoft.AspNetCore.Mvc.ApiExplorer;using System;using System.Collections.Generic;using System.Linq;using System.Threading.Tasks;namespace ItSys.ApiGroup{///<summary>///系统分组特性///</summary>public class ApiGroupAttribute : Attribute, IApiDescriptionGroupNameProvider{public ApiGroupAttribute(ApiGroupNames name){GroupName = name.ToString();}public string GroupName { get; set; }}}ApiGroupNames.cs代码如下using System;using System.Collections.Generic;using System.Linq;using System.Threading.Tasks;namespace ItSys.ApiGroup{///<summary>///系统分组枚举值///</summary>public enum ApiGroupNames{[GroupInfo(Title ="登录认证",Description ="登录认证相关接⼝",Version ="v1")]Auth,[GroupInfo(Title = "IT", Description = "登录认证相关接⼝")]It,[GroupInfo(Title = "⼈⼒资源", Description = "登录认证相关接⼝")]Hr,Cw}}GroupInfoAttribute.cs代码如下using System;using System.Collections.Generic;using System.Linq;using System.Threading.Tasks;namespace ItSys.ApiGroup{///<summary>///系统模块枚举注释///</summary>public class GroupInfoAttribute : Attribute{public string Title { get; set; }public string Version { get; set; }public string Description { get; set; }}}打开Startup.cs⽂件修改ConfigureServices⽅法（为了⽅便查看，只列出关于Swagger分组的关键代码）public void ConfigureServices(IServiceCollection services){#region Swaggerservices.AddSwaggerGen(options =>{//遍历ApiGroupNames所有枚举值⽣成接⼝⽂档，Skip(1)是因为Enum第⼀个FieldInfo是内置的⼀个Int值typeof(ApiGroupNames).GetFields().Skip(1).ToList().ForEach(f =>{//获取枚举值上的特性var info = f.GetCustomAttributes(typeof(GroupInfoAttribute), false).OfType<GroupInfoAttribute>().FirstOrDefault();options.SwaggerDoc(, new {Title = info?.Title,Version = info?.Version,Description = info?.Description});});//没有加特性的分到这个NoGroup上options.SwaggerDoc("NoGroup", new {Title = "⽆分组"});//判断接⼝归于哪个分组options.DocInclusionPredicate((docName, apiDescription) =>{if (docName == "NoGroup"){//当分组为NoGroup时，只要没加特性的都属于这个组return string.IsNullOrEmpty(apiDescription.GroupName);}else{return apiDescription.GroupName == docName;}});}修改Configure⽅法public void Configure(IApplicationBuilder app, IHostingEnvironment env){#region SwaggereSwagger();eSwaggerUI(options =>{//遍历ApiGroupNames所有枚举值⽣成接⼝⽂档，Skip(1)是因为Enum第⼀个FieldInfo是内置的⼀个Int值typeof(ApiGroupNames).GetFields().Skip(1).ToList().ForEach(f =>{//获取枚举值上的特性var info = f.GetCustomAttributes(typeof(GroupInfoAttribute), false).OfType<GroupInfoAttribute>().FirstOrDefault();options.SwaggerEndpoint($"/swagger/{}/swagger.json", info != null ? info.Title : );});options.SwaggerEndpoint("/swagger/NoGroup/swagger.json", "⽆分组");});#endregion}然后你F6⽣成⼀下，没出错的话，就Ctrl+F5看看，正常的话就会在Swagger右上⾓看到分组了。

coreSwashbuckleSwagger的常⽤配置背景我们发现很多⼩伙伴⽇常使⽤ Swashbuckle Swagger 都不看⽂档的，写下常需⽤到的配置/写法；基本使⽤Package Manager : Install-Package Swashbuckle.AspNetCore记得⽤swagger⼀定要给action打[httpmehtod]标签[HttpGet]public IEnumerable<Product> SearchProducts([FromQuery]string keywords)public static IServiceCollection AddSwagger(this IServiceCollection services){services.AddSwaggerGen(c =>{c.SwaggerDoc("v1", new OpenApiInfo{Version = "v1",Title = "test api",});//多个xml⽂件var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";var xmlPath = bine(AppContext.BaseDirectory, xmlFile);var dtoXmlPath = bine(AppContext.BaseDirectory, $"{typeof(BaseIdEntity).Assembly.GetName().Name}.xml");c.IncludeXmlComments(xmlPath);c.IncludeXmlComments(dtoXmlPath);});return services;}public static IApplicationBuilder UseSwagger(this IApplicationBuilder app){//配置⼆级⽬录var basePath = "/testapi";eSwagger(c =>{c.PreSerializeFilters.Add((swaggerDoc, httpReq) => swaggerDoc.Servers = new List<OpenApiServer> { new OpenApiServer { Url = $"{basePath}" } }); });eSwaggerUI(c =>{c.SwaggerEndpoint($"{ basePath}/swagger/v1/swagger.json", "FitnessApi V1");});return app;}多版本⽀持services.AddSwaggerGen(c =>{c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API - V1", Version = "v1" });c.SwaggerDoc("v2", new OpenApiInfo { Title = "My API - V2", Version = "v2" });})[HttpPost][ApiExplorerSettings(GroupName = "v2")]public void Post([FromBody]Product product)更完善的枚举⽀持Install-Package Unchase.Swashbuckle.AspNetCore.Extensionsservices.AddSwaggerGen(options =>{//...// or configured:options.AddEnumsWithValuesFixFilters(services, o =>{// add schema filter to fix enums (add 'x-enumNames' for NSwag) in schemao.ApplySchemaFilter = true;// add parameter filter to fix enums (add 'x-enumNames' for NSwag) in schema parameterso.ApplyParameterFilter = true;// add document filter to fix enums displaying in swagger documento.ApplyDocumentFilter = true;// add descriptions from DescriptionAttribute or xml-comments to fix enums (add 'x-enumDescriptions' for schema extensions) for applied filterso.IncludeDescriptions = true;// add remarks for descriptions from xml-commentso.IncludeXEnumRemarks = true;// get descriptions from DescriptionAttribute then from xml-commentso.DescriptionSource = DescriptionSources.DescriptionAttributesThenXmlComments;// get descriptions from xml-file comments on the specified path// should use "options.IncludeXmlComments(xmlFilePath);" beforeo.IncludeXmlCommentsFrom(xmlFilePath);// the same for another xml-files...});});枚举⽂档效果OAuth2.0⽀持Install-Package Swashbuckle.AspNetCore.Filters⼿填AccessToken(apikey)⽅式services.AddSwaggerGen(c =>{//...c.OperationFilter<SecurityRequirementsOperationFilter>();c.AddSecurityDefinition("oauth2", new OpenApiSecurityScheme{Description = "Standard Authorization header using the Bearer scheme. Example: \"bearer {token}\"", In = ParameterLocation.Header,Name = "Authorization",Type = SecuritySchemeType.ApiKey});});效果引导跳转OAuth服务器⽅式services.AddSwaggerGen(c =>{//...c.OperationFilter<SecurityRequirementsOperationFilter>();c.AddSecurityDefinition("oauth2", new OpenApiSecurityScheme{Type = SecuritySchemeType.OAuth2,Flows = new OpenApiOAuthFlows(){Implicit = new OpenApiOAuthFlow(){AuthorizationUrl = new Uri("https://your.identityserver.io/connect/authorize"),Scopes = new Dictionary<string, string>{{ "testapi.rw", "授权访问测试TestApi" }}}}});});eSwaggerUI(c =>{//...c.OAuthClientId("test_swaager");});效果忽略某个Api[HttpGet("{id}")][ApiExplorerSettings(IgnoreApi = true)]public Product GetById(int id)修改传输数据类型services.AddSwaggerGen(c =>{//long类型转stringc.MapType<long>(() => new OpenApiSchema { Type = "string" });});⾃定义描述（标签）Install-Package Swashbuckle.AspNetCore.Annotations[SwaggerTag("Create, read, update and delete Products")]public class ProductsController{...}Quer请求参数⼩驼峰public class QueryBillDto{/// <summary>/// PID/⼿机号/昵称/// </summary>public string Query { get; set; }/// <summary>////// </summary>public EApp? Appid { get; set; }/// <summary>/// 收⼊/⽀出类型/// </summary>public EnumBillType? BillType { get; set; }/// <summary>/// 账单起始⽇期/// </summary>public DateTime? BillBegin { get; set; }/// <summary>/// 账单截⽌⽇期/// </summary>public DateTime? BillEnd { get; set; }}...//⽐如定义了这样的接⼝public async Task<IActionResult> GetBillList([FromQuery] QueryBillDto dto) {return Ok();}swagger-ui需要显⽰为⼩写的这样：services.AddSwaggerGen(c =>{//参数描述⼩驼峰o.DescribeAllParametersInCamelCase();});。

一、背景介绍.NET Core 是微软推出的一种开源的跨评台开发框架，其主要目的是让开发人员能够在多种操作系统上构建各种类型的应用程序。

Swagger 是一种流行的 API 文档生成工具，可以自动生成API的文档，让开发人员能够更加方便地理解和使用API接口。

在.NET Core 中使用Swagger，可以通过对API的参数进行注释，来实现更加详细的文档生成，帮助其他开发人员更加方便地使用API接口。

二、Swagger 参数注释的重要性1. 详细说明参数用途在编写API接口时，会有许多参数需要传递给接口，这些参数的作用有时候并不是很清晰。

如果能够对参数进行详细的注释，就可以让其他开发人员更加容易地理解这些参数的作用，从而更加方便地使用接口。

2. 自动生成文档Swagger 可以根据参数的注释自动生成文档，如果参数注释不够清晰或者不完整，生成的文档就会变得不够完善，给其他开发人员带来不便。

3. 提高协作效率在团队开发中，不同的开发人员可能会编写不同的API接口，使用Swagger 对参数进行注释可以帮助团队成员更好地协作，减少交流成本。

三、Swagger 参数注释的方法1. 使用 XML 注释在 .NET Core 中，可以通过在代码中使用 XML 注释的方式对参数进行注释，Swagger 可以读取这些注释并生成文档。

2. 使用特定的标签除了XML 注释外，还可以在代码中使用特定的标签来进行参数的注释，这些标签会被Swagger 解析并生成文档。

四、示例下面是一个使用 .NET Core 编写的API接口的示例，以及对参数进行注释的方法。

```csharp/// <summary>/// 用户服务/// </summary>[ApiController][Route("api/[controller]")]public class UserController : ControllerBase{/// <summary>/// 获取用户信息/// </summary>/// <param name="userId">用户ID</param>/// <param name="userName">用户名</param>/// <returns>用户信息</returns>[HttpGet]public ActionResult<UserInfo> GetUserInfo(int userId, string userName){// 处理业务逻辑return new UserInfo();}}```在上面的示例中，对于 GetUserInfo 方法中的 userId 参数和userName 参数进行了注释，通过注释可以清晰地说明这两个参数的作用，以及返回值的含义。

netcore swagger高级用法在使用NetCore Swagger进行API文档生成时，除了基本的用法外，还有一些高级用法可以提供更多定制化的功能和优化体验。

本文将介绍几个常用的NetCore Swagger高级用法。

1. 定制路由前缀通过Swagger的配置，可以为API文档添加路由前缀，方便进行不同模块的区分。

可以通过`SwaggerGenOptions`中的`RoutePrefix`属性来设置路由前缀。

例如，如果我们想要为文档的所有API添加前缀`/api/v1`，可以在配置文件中添加如下代码：```csharpservices.AddSwaggerGen(c =>{c.RoutePrefix = "api/v1";});```2. 隐藏指定的API接口有时候我们希望某些API接口不在文档中显示，可以通过使用Swagger注解来实现。

在需要隐藏的接口上添加`[ApiExplorerSettings(IgnoreApi = true)]`注解即可。

例如：```csharp[HttpGet][ApiExplorerSettings(IgnoreApi = true)]public IActionResult HiddenEndpoint(){// 隐藏的接口逻辑}```3. 添加接口备注和示例请求为了提供更友好的API文档，我们可以通过Swagger的注解来为接口添加备注和示例请求。

使用`Summary`和`Remarks`可以添加接口的概要和详细说明，示例如下：```csharp[HttpPost][Summary("创建新用户")][Remarks("此接口用于创建新用户")]public IActionResult CreateUser([FromBody] User user){// 创建用户逻辑}```使用`Example`来添加示例请求，方便用户理解接口的使用方法。