Net Core的API文档工具Swagger

1、安装swagger

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

2、注册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方法没有绑定因此报错了，解决方法有两个：

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

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

3、文档的描述

　　一、接口描述

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

 

 　　而后在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) { }

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

 　　二、版本的描述

　　对于接口，随着版本的迭代会有不少的版本，因此经过版本的描述能够更简单的找到对应的接口。对于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")]。若是不设置那这任何版本中都会出现。效果以下：

 4、swagger其余补充

　　一、swagger支持token受权认证

　　二、swagger生成离线文档

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