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接口多版本控制補充