swagger的作用和配置使用（多版本操作

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

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

   

---

 

引入包

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

配置

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

public void ConfigureServices(IServiceCollection services)
        {
            //swagger服务配置
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("V1", new Microsoft.OpenApi.Models.OpenApiInfo
                {
                    Version = "v1",//接口文档版本
                    Title = "我的接口文档1.0",//接口文档标题
                    Description = "我的第一个swagger文档",//接口文档描述
                    Contact = new Microsoft.OpenApi.Models.OpenApiContact { Name = "张华", Url = new Uri("http://baidu.com"), Email = "nice0320@163.com" },
                    License = new Microsoft.OpenApi.Models.OpenApiLicense { Name = "张华", Url = new Uri("http://baidu.com") }
                });
            });
            services.AddControllers();
        }

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

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }

            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });

            ///swagger中间件启动配置
            app.UseSwagger();
            app.UseSwaggerUI(a => {
                a.SwaggerEndpoint("/swagger/V1/swagger.json", "中间件启动配置，我的第一个swagger文档");
                //如果是为空 访问路径就为 根域名/index.html,注意localhost:8001/swagger是访问不到的
                //路径配置，设置为空，表示直接在根域名（localhost:8001）访问该文件
                // c.RoutePrefix = "swagger"; // 如果你想换一个路径，直接写名字即可，比如直接写c.RoutePrefix = "swagger"; 则访问路径为 根域名/swagger/index.html
                a.RoutePrefix = string.Empty;//路由
            });
        }

注意：

新建项目第一次配置完成运行的时候可能如下所示。因为 /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：个人小小理解，希望有错误可以指正