.netcore入门19：aspnetcore集成Swagger

环境：

• .netcore 3.1.1
• vs 2019 16.4.5
• Swashbuckle.AspNetCore 5.0.0

一、关于swagger说明

在使用asp.net core 进行api开发完成后，书写api说明文档对于程序员来说想必是件很痛苦的事情吧，但文档又必须写，而且文档的格式如果没有具体要求的话，最终完成的文档则完全取决于开发者的心情。或者详细点，或者简单点。那么有没有一种快速有效的方法来构建api说明文档呢？答案是肯定的， Swagger就是最受欢迎的REST APIs文档生成工具之一！

swagger官网：https://swagger.io/
参考：ASP.NET Core WebApi使用Swagger生成api说明文档看这篇就够了

二、简单webapi项目集成swagger

2.1 准备webapi项目

这里新建一个空白的wenapi项目即可。

2.2 安装swagger的nuget包

2.3 在工程属性上开启xml文档生成

2.4 在方法和模型上添加注释

2.5 向容器中注册swagger服务

public void ConfigureServices(IServiceCollection services)
{
    services.AddSwaggerGen(options =>
    {
        options.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo { Title = "My API", Version = "v1" });
        var xmlPath = Path.Combine(env.ContentRootPath, Assembly.GetExecutingAssembly().GetName().Name + ".xml");
        if (File.Exists(xmlPath))
        {
            options.IncludeXmlComments(xmlPath);
        }
    });
    services.AddControllers();
}

说明：
注意上面代码中有指定生成的xml文档的地址，如果不指定的话，浏览器也会显示接口以及参数名称，但是就不会显示你写的注释，所以一定要手动将xml文档的地址配置上去。还有，在生成工程的时候Release模式下是不会输出xml文档的，所以要注意这个文件是否存在（上面代码中已自动判断）。

2.6 注册swagger中间件

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    app.UseHttpsRedirection();
    app.UseSwagger();
    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
        //如果不想带/swagger路径访问的话，就放开下面的注释
        //options.RoutePrefix = string.Empty;
    });
    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

2.7 直接调试运行

浏览器中输入： http://localhost:5000/swagger

2.8 隐藏某个控制器或Action不显示

如果你不想针对某个控制器或某个方法就在上面打上标记[ApiExplorerSettings(IgnoreApi = true)]就行，这样浏览器页面中就不会出现这个控制器或方法了，如下图：

三、带身份认证的webapi项目集成swagger

四、多项目模块使用swagger