.net core 3.1简单swagger配置教程

前言

当今前后端分离开发已经成为一种大趋势，那后端开发人员给前端开发人员接口文档，无非就两种形式，手写接口文档跟在线接口文档。这时候引用swagger，让后端人员摆脱重复工作的麻烦。

开始

1、新建项目

随便新建个空的webapi项目

2、引入Swagger包。

.Net Core 中支持两个分别为Swashbuckle和NSwag。两者的配置大同小异。这里以Swashbuckle为例。

3、配置Swagger中间件

3.1 在Startup类ConfigureServices方法中添加Swagger服务并配置文档信息

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();
            // 注册Swagger服务
            services.AddSwaggerGen(c =>
            {
                // 添加文档信息
                c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo { Title = "CoreWebApi", Version = "v1" });
            });
        }

3.2 在 Configure 方法中，启用中间件为生成的 JSON 文档和 Swagger UI 提供服务

            //启用中间件服务生成Swagger作为JSON终结点
            app.UseSwagger();
            //启用中间件服务对swagger-ui，指定Swagger JSON终结点
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
            });

3.3 启动项目测试swagger是否配置成功
输入默认端口https://localhost:5001/swagger/index.html测试，当出现如图所示，则表示成功配置。

4、关键步骤（配置xml注释）

4.1右击项目=》属性=》生成，修改以下配置。

4.2 重新打开Startup类，找到AddSwaggerGen（）方法中读取xml文件路径并启用

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();
            // 注册Swagger服务
            services.AddSwaggerGen(c =>
            {
                // 添加文档信息
                c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo { Title = "CoreWebApi", Version = "v1" });

                // 使用反射获取xml文件。并构造出文件的路径
                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                // 启用xml注释. 该方法第二个参数启用控制器的注释，默认为false.
                c.IncludeXmlComments(xmlPath, true);
            });
        }

这时候我们重新生成项目会发现项目根目录下产生一个xml文件

测试接口的注释信息

        /// <summary>
        /// 这是一个带参数的get请求
        /// </summary>
        /// <remarks>
        /// 例子:
        /// Get api/Values/1
        /// </remarks>
        /// <param name="id">主键</param>
        /// <returns>测试字符串</returns>  
        [HttpGet("{id}")]
        public string Get(int id)
        {
            return "value";
        }

测试结果如图，我们本次的swagger配置几乎就已经大功告成了。

注意事项

1、以上都是本地运行测试，假如要生成发布部署到服务器，会出错，是因为默认的xml不会生成到文件夹里，需要右击更改xml文件的属性

2、以目前流行的三层开发模式，一般请求跟返回实体，我们会放在model层那边，因人而异，但假如我们的Controller层引用任何一个程序集的实体，同时也想让该程序集的实体注释生成，同样也需要配置开启xml注释，如图所示

响应实体类

    /// <summary>
    /// 返回实体
    /// </summary>
    public class SwaggerResponse
    {

        /// <summary>
        /// 编码
        /// </summary>
        public int code { get; set; }
        /// <summary>
        /// 数据
        /// </summary>
        public string data { get; set; }
    }

控制器方法调整

        /// <summary>
        /// 这是一个带参数的get请求
        /// </summary>
        /// <remarks>
        /// 例子:
        /// Get api/Values/1
        /// </remarks>
        /// <param name="id">主键</param>
        /// <returns>测试字符串</returns>  
        [HttpGet("{id}")]
        public SwaggerResponse Get(int id)
        {
            var obj = new SwaggerResponse { code = 200, data = "hello,world!" };
            return obj;
        }

重新运行项目，如图所示则表示成功。