Net Core的API文档工具Swagger

一、安装swagger

　　新建一个net core的api项目，通过NuGet安装Swashbuckle.AspNetCore。

二、注册swagger服务

　　在Startup.cs中注册Swagger生成器。

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
            //注册Swagger生成器，定义一个和多个Swagger 文档
            #region Swagger
            services.AddSwaggerGen(options =>
            {
                options.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
            });
            #endregion
        }

　　启用Swagger。

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

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

            app.UseHttpsRedirection();
            app.UseMvc();
        }

　　控制器如下。

    [Route("api/[controller]")]
    [ApiController]
    public class ValuesController : ControllerBase
    {
        public ActionResult<string> Get()
        {
            return "value";
        }
        [HttpPost]
        public void Post([FromBody] string value)
        {
        }
        [HttpPut("{id}")]
        public void Put(int id, [FromBody] string value)
        {
        }
        [HttpDelete("{id}")]
        public void Delete(int id)
        {
        }
    }

　　启动项目，访问路径/swagger，就可以看到文档内容了，但是我们可以发现报错如下。

 　　访问路径/swagger/v1/swagger.json可以发现，swagger需要显示绑定http方法，由于第一个get方法没有绑定所以报错了，解决方法有两个：

　　1、显示绑定http方法，如添加特性[HttpGet]等。

　　2、添加特性[ApiExplorerSettings(IgnoreApi = true)]，让swagger忽略这个接口。

三、文档的描述

　　1、接口描述

　　首先需要设置文档的输出路径，进入项目的属性->生成，设置输出路径如下

 　　然后在Startup.cs->ConfigureServices方法中设置输出路径

            services.AddSwaggerGen(options =>
            {
                options.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
                // 设置SWAGER JSON和UI的注释路径。
                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                options.IncludeXmlComments(xmlPath);
            });

　　对于接口的注释和我们平常的注释一样。

        /// <summary>
        /// 提交数据
        /// </summary>
        /// <remarks>
        /// 备注：返回数据。。。
        /// </remarks>
        /// <param name="value">值</param>
        /// <response code="200">返回成功</response>
        /// <response code="500">返回失败</response>  
        [HttpPost]
        public void Post([FromBody] string value)
        {
        }

　　对于没有注释的方法会报警告，如果不喜欢就可以在项目的属性->生成中设置隐藏

 　　2、版本的描述

　　对于接口，随着版本的迭代会有很多的版本，所以通过版本的描述可以更简单的找到对应的接口。对于swagger可以添加多个文档的描述并且设置多个终结点显示不同版本的接口文档。

        public void ConfigureServices(IServiceCollection services)
        {
            //注册Swagger生成器，定义一个和多个Swagger 文档
            #region Swagger
            services.AddSwaggerGen(options =>
            {
                options.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1", Contact = new Contact { Name = "小小开发者", Email = "   think@mr_lv" } });
                options.SwaggerDoc("v2", new Info { Title = "My API", Version = "v2", Contact = new Contact { Name = "小小开发者", Email = "   think@mr_lv" } });
            });
            #endregion
        }

        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            #region Swagger
            //启用中间件服务生成Swagger作为JSON终结点
            app.UseSwagger();
            //启用中间件服务对swagger-ui，指定Swagger JSON终结点
            app.UseSwaggerUI(options =>
            {
                options.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
                options.SwaggerEndpoint("/swagger/v2/swagger.json", "v2");
            });
            #endregion
        }

　　这里要特别注意不同的版本名称对应不同的终结点。不对应会导致一直只有一种的尴尬。当然我们的接口也需要设置属于那个版本通过特性[ApiExplorerSettings(GroupName = "v1")]。如果不设置那这任何版本中都会出现。效果如下：

 四、swagger其他补充

　　1、swagger支持token授权认证

　　2、swagger生成离线文档

　　3、swagger接口多版本控制补充