在学习net core中接触到了swagger、学习并记录
纯API项目中 引入swagger可以生成可视化的API接口页面
![官方样式 官方样式](https://img2022.cnblogs.com/blog/2125261/202203/2125261-20220331172438142-1845774519.png)
引入包
nuget包: Swashbuckle.AspNetCore(最新稳定版)
配置
1.配置Startup类ConfigureServices方法的相关配置
![](https://images.cnblogs.com/OutliningIndicators/ContractedBlock.gif)
1 public void ConfigureServices(IServiceCollection services) 2 { 3 //swagger服务配置 4 services.AddSwaggerGen(c => 5 { 6 c.SwaggerDoc("V1", new Microsoft.OpenApi.Models.OpenApiInfo 7 { 8 Version = "v1",//接口文档版本 9 Title = "我的接口文档1.0",//接口文档标题 10 Description = "我的第一个swagger文档",//接口文档描述 11 Contact = new Microsoft.OpenApi.Models.OpenApiContact { Name = "张华", Url = new Uri("http://baidu.com"), Email = "nice0320@163.com" }, 12 License = new Microsoft.OpenApi.Models.OpenApiLicense { Name = "张华", Url = new Uri("http://baidu.com") } 13 }); 14 }); 15 services.AddControllers(); 16 }
2.配置Startup类Configure方法的中间件
![](https://images.cnblogs.com/OutliningIndicators/ContractedBlock.gif)
1 public void Configure(IApplicationBuilder app, IWebHostEnvironment env) 2 { 3 if (env.IsDevelopment()) 4 { 5 app.UseDeveloperExceptionPage(); 6 } 7 8 app.UseRouting(); 9 10 app.UseAuthorization(); 11 12 app.UseEndpoints(endpoints => 13 { 14 endpoints.MapControllers(); 15 }); 16 17 ///swagger中间件启动配置 18 app.UseSwagger(); 19 app.UseSwaggerUI(a => { 20 a.SwaggerEndpoint("/swagger/V1/swagger.json", "中间件启动配置,我的第一个swagger文档"); 21 //如果是为空 访问路径就为 根域名/index.html,注意localhost:8001/swagger是访问不到的 22 //路径配置,设置为空,表示直接在根域名(localhost:8001)访问该文件 23 // c.RoutePrefix = "swagger"; // 如果你想换一个路径,直接写名字即可,比如直接写c.RoutePrefix = "swagger"; 则访问路径为 根域名/swagger/index.html 24 a.RoutePrefix = string.Empty;//路由 25 }); 26 }
注意:
新建项目第一次配置完成运行的时候可能如下所示。因为 /WeatherForecast 是官方默认的地址
解决方案:Properties文件夹下launchSettings.json文件launchUrl属性改为null
launchUrl代表浏览器里启动相对的URL
4-14更新:
虽然配置好了swagger,但是众多接口也不好分辨,因此我们需要给接口添加注释
1,右键项目属性-生成-输出(将文档文件勾选,路径可默认可以自己设置)
2,在 Startup.cs文件ConfigureServices方法配置服务(上面配置swagger的地方)
public void ConfigureServices(IServiceCollection services) { services.AddControllers(); //配置swagger services.AddSwaggerGen(a => { a.SwaggerDoc("CoreOne_Zhang", new Microsoft.OpenApi.Models.OpenApiInfo { Version = "第一版", Title = "CoreOne_Zhang的Swagger第一版", Description = "专有", Contact = new Microsoft.OpenApi.Models.OpenApiContact { Email = "nicezh0320@163.com", Url = new Uri("https://jq.qq.com/?_wv=1027&k=GecDlZAd"), Name = "张华" } }); //xml文档路径 var basePath = AppContext.BaseDirectory; //将路径和文件拼接 var xmlPath = Path.Combine(basePath, "NetCore.OneApi.xml"); //将xml文档注入。true表示是否显示控制器注释,默认false a.IncludeXmlComments(xmlPath,true); });
2022:4-20更新:Swagger多版本操作
可以将不同的接口分别展示
接上文。设置好swagger后,我们需要设置多个版本(页面?)
1,可以先创建一个 版本类。(枚举类型)
2,将原本固定写死的版本号,利用 版本类 循环输出
typeof循环在SwaggerDoc之外。
services.AddSwaggerGen(s => { typeof(SwaggerType).GetEnumNames().ToList().ForEach(version => { s.SwaggerDoc(version, new OpenApiInfo { Version = version, Title = "欢迎一起学习", Description = "多版本自定义API", Contact = new OpenApiContact { Name = "张华", Url = new Uri("https://jq.qq.com/?_wv=1027&k=mwVO65PG") }, License = new OpenApiLicense { Name = "张华", Url = new Uri("https://jq.qq.com/?_wv=1027&k=mwVO65PG") } }); var path = System.AppDomain.CurrentDomain.BaseDirectory; var xmlPath = System.IO.Path.Combine(path, "NetNotes.xml"); s.IncludeXmlComments(xmlPath, true); }); });
同理,中间件也需要配置循环一下,只要将SwaggerEndpoint,RoutePrefix外面循环 版本输出即可
app.UseSwagger(); app.UseSwaggerUI(a => { typeof(SwaggerType).GetEnumNames().ToList().ForEach(V => { a.SwaggerEndpoint($"swagger/{V}/swagger.json", $"版本{V}"); a.RoutePrefix = ""; }); });
3,将不同的接口展示在不同的版本页面
只需要加 [ApiExplorerSettings(GroupName ="Zhang")] Zhang可以替换成你 版本 类里面的任何一个,那么他就只显示在你规定的版本页面当中
运行效果:
//效果显示地址:Swagger UI
//一起学习,Git克隆地址:NetCore学习: NetCore学习 Master:swagger Jwt:Jwt身份验证登录 (gitee.com)
Ps:个人小小理解,希望有错误可以指正