.Net Core2.2 使用Swagger UI做接口文档

一个解决方案下有多个项目。如Entity库，LogicHandler库，Repository库，Util库，Mvc项目库等。

开始

一、项目引用Swagger的nuget包

二、配置服务

在ConfigureServices处添加如下:

    //非正式环境显示Swagger页面；
            if (!_hostingEnvironment.IsProduction())
            {
                services.AddSwaggerGen(c =>
                {
                    c.SwaggerDoc("v1", new Info { Title = "Insurance API", Version = "v1" });
                    var mvcXmlFile = $"{ Assembly.GetEntryAssembly().GetName().Name }.xml";
                    var entityXmlFile = $"Insurance.Entity.xml";
                    var mvcXmlPath = Path.Combine(AppContext.BaseDirectory, mvcXmlFile);
                    var entityXmlPath = Path.Combine(AppContext.BaseDirectory, entityXmlFile);
                    c.IncludeXmlComments(mvcXmlPath);
                    c.IncludeXmlComments(entityXmlPath);
                });
            };

三、中间件启用

在Configure中添加如下:

 if (!_hostingEnvironment.IsProduction())
            {
                app.UseSwagger();
                app.UseSwaggerUI(c =>
                {
                    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Insurance API");
                });
            }

至此Swagger的配置基本完成，若要使启动项目的默认启动地址为swagger界面，可以去启动项目中的launchSetting.json文件处修改，

使用

一、修改项目属性

为项目的接口添加注释后，然后在右键点击启动项目的属性中的生成处，启用xml文档文件，一般输出路径为bin\Debug

由于mvc项目引用了Entity类库，Entity类库中有很多Dto类，Dto有很多注释，此时对Entity项目进行以上操作，但注意的是，一定要使Entity项目的xml文档输出路径与mvc项目的输出路径一致，这样在Startup类的ConfigureServices中方便找出

二、关于接口中Dto的注释说明

如果说参数是必填的需要加上[Required]头，如果参数非必填如数字之类的需要在类型后面打**?**来说明此值可为空。

三、隐藏接口

添加**[ApiExplorerSettings(IgnoreApi = true)]**，可在controller中，也可在Action中

四、忽略Swagger的注释警告

可在启动项目中的属性中的错误和警示处添加代码 1591;

关于.Net Core3.1的配置可去查看艾三元的文章,本篇有从该作者处获取到知识。