.Net Core中使用Swagger,以及显示注释

简介:

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。.

安装

使用Nuget搜索Swashbuckle.AspNetCore

配置

在Configure方法中配置中间件

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

            app.UseRouting();
            //Swagger面板
            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v0/swagger.json", "测试");
            });
            app.UseAuthorization();

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

在ConfigureServices配置服务

public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();
            // 添加Swagger
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v0", new OpenApiInfo { Title = "测试", Version = "1.0.0.0" });
                // 获取xml文件名
                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                // 获取xml文件路径
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                //是否显示注释
                c.IncludeXmlComments(xmlPath, true);
            });

        }

生成XML

右键项目属性->生成->勾选XML

使用

在ControllerBase带入    [ApiExplorerSettings(GroupName = "v0")] 

查看Swagger文档 

启动项目后，对默认的地址后加上“/swagger”即可进入swagger API文档