在学习net core中接触到了swagger、学习并记录

纯API项目中 引入swagger可以生成可视化的API接口页面

引入包

nuget包： Swashbuckle.AspNetCore（最新稳定版）

配置

1.配置Startup类ConfigureServices方法的相关配置

//配置Startup类ConfigureServices方法的相关配置
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方法的中间件

//配置Startup类Configure方法的中间件
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         }

2.配置Startup类Configure方法的中间件

注意：

新建项目第一次配置完成运行的时候可能如下所示。因为 /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(#34;swagger/{V}/swagger.json", #34;版本{V}");
                    a.RoutePrefix = "";
                });
            });

3，将不同的接口展示在不同的版本页面

只需要加[ApiExplorerSettings(GroupName ="Zhang")] Zhang可以替换成你 版本 类里面的任何一个，那么他就只显示在你规定的版本页面当中

运行效果：

//效果显示地址：Swagger UI

//一起学习，Git克隆地址：NetCore学习: NetCore学习 Master：swagger Jwt:Jwt身份验证登录 (gitee.com)

Ps：欢迎一起学习