【WebAPI No.4】Swagger實現API文件功能
介紹:
Swagger也稱為Open API,Swagger從API文件中手動完成工作,並提供一系列用於生成,視覺化和維護API文件的解決方案。簡單的說就是一款讓你更好的書寫API文件的框架。
我們為什麼選擇swagger,現在的網站開發結果越來越注重前後端的分離,比如以前的webFrom到現在的mvc模式都是為了這個前後端的分離。就算再如何的分離實現,也是不可避免的要進行資料互動的,那麼介面的重要性就提現出來了。他成了前端和後端互動的重要途徑,API文件也因此成了前端開發人員與後端開發人員的重要紐帶。所有我們有一個API文件框架豈不是美哉。
Swashbuckle有三個主要元件:
Swashbuckle.AspNetCore.Swagger:Swagger物件模型和中介軟體,將SwaggerDocument物件公開為JSON端點。
Swashbuckle.AspNetCore.SwaggerGen:一種Swagger生成器,可SwaggerDocument直接從路由,控制器和模型構建物件。它通常與Swagger端點中介軟體結合使用,以自動公開Swagger JSON。
Swashbuckle.AspNetCore.SwaggerUI:Swagger UI工具的嵌入式版本。它將Swagger JSON解釋為構建豐富的,可定製的Web API功能描述體驗。它包括用於公共方法的內建測試線束。
開始使用:
首先我們要有一個WebAPI專案,假設我們已經建立好了,不懂WebAPI如何建立的請看這篇文章:建立簡單的WebAPI
好了現在我們已經有了專案那我們就開始新增引用吧:
Nuget 命令列 :Install-Package Swashbuckle.AspNetCore
新增並配置Swagger中介軟體:
然後配置Startup.cs 檔案中的ConfigureServices方法,當然首先不要忘記引用一下using Swashbuckle.AspNetCore.Swagger名稱空間,不然info類會報錯。
public void ConfigureServices(IServiceCollection services) { services.AddMvc() .SetCompatibilityVersion(CompatibilityVersion.Version_2_1) .AddJsonOptions(options=> options.SerializerSettings.ContractResolver = new Newtonsoft.Json.Serialization.DefaultContractResolver());//JSON首字母小寫解決; services.AddSwaggerGen(options => { options.SwaggerDoc("v1", new Info { Version = "v1", Title = " API 文件" }); }); }
然後在Configure方法中新增:
//允許中介軟體為JSON端點服務生成的Siggg app.UseSwagger(); //使中介軟體能夠服務於輕量級使用者介面(HTML、JS、CSS等),並指定SWAGJER JSON端點 app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); // 要在應用程式的根處提供Swagger UI ,請將該RoutePrefix屬性設定為空字串 c.RoutePrefix = string.Empty; });View Code
啟動效果:
這樣就可以啟動了,配置好以上就是一個最簡單的api文件示例了。首先你可以訪問:http://localhost:<port>/swagger/v1/swagger.json 這個網址看到端點生成的文件。
當然你想看到的是這個:http://localhost:<port>/swagger ,你輸入這個網址也可以,當然我把他配置成了根節點,這樣直接啟動根節點就是該頁面。主要是上面程式碼中的: c.RoutePrefix = string.Empty這句程式碼。
擴充套件一些顯示:
我們可以擴充套件一些附加資訊,比如作者,許可證,服務條款等。傳遞給該AddSwaggerGen
方法的配置:
//Swagger生成器新增到方法中的服務集合中 services.AddSwaggerGen(options => { options.SwaggerDoc("v1", new Info { Version = "v1", Title = " API 文件", Description = "這是一個示例webapi文件", //服務條款 TermsOfService = "None", //作者資訊 Contact = new Contact { Name = "ybf", Email = string.Empty, Url = "http://www.cnblogs.com/yanbigfeg/" }, //許可證 License = new License { Name = "許可證名字", Url = "http://www.cnblogs.com/yanbigfeg/" } }); });View Code
顯示結果
xml註釋:
啟用XML註釋可為未記錄的公共型別和成員提供除錯資訊。未記錄的型別和成員由警告訊息指示。配置Swagger以使用生成的XML檔案。
在我們實現前先設定一下專案屬性:
這樣就可以在專案bin下生成xml檔案了。下面進行程式碼配置啟用,還是在Startup類中的ConfigureServices方法中,在我們剛才配置的下面在增加以下程式碼:
// 設定SWAGER JSON和UI的註釋路徑。 var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"; var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile); options.IncludeXmlComments(xmlPath);
使用反射主要是為了生成一個與專案檔名相同的xml檔案。第二部然後是配置檔案路徑。這些配置好了以後。我們就可以把方法或者類的三道斜槓(“///”)的註釋新增到動作。我們來看一下效果。
程式碼
介面:
注意哦,就是開啟這個功能,專案會自動檢測那些方法或者類沒有註釋,會給出警告。
取消警告小技巧:
當然我們也可以取消掉:我們在個人.csproj檔案中使用分號分隔來取消警告資訊:
<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'"> <DocumentationFile>bin\Debug\netcoreapp2.1\SwaggerTest.xml</DocumentationFile> <GenerateSerializationAssemblies>On</GenerateSerializationAssemblies> <NoWarn>1701;1702;1705;1591</NoWarn> </PropertyGroup>View Code
這樣就不會有警告提示了。
描述相應型別:
介面使用者最關心的就是介面的返回內容和相應型別啦。下面展示一下201和400一個簡單例子:
我們需要在我們的方法上新增:[ProducesResponseType(201)][ProducesResponseType(400)]
然後新增相應的狀態說明:<response code="201">返回value字串</response><response code="400">如果id為空</response>
最終程式碼應該是這個樣子:
/// <summary> /// values帶id引數的get /// </summary> /// <param name="id">id引數</param> /// <returns>返回字串型別</returns> /// <response code="201">返回value字串</response> /// <response code="400">如果id為空</response> // GET api/values/5 [HttpGet("{id}")] [ProducesResponseType(201)] [ProducesResponseType(400)] public ActionResult<string> Get(int id) { return "value"; }View Code
執行起來我們看一下結果:
傳送門:
WebApi系列文章介紹如何使用WebAPI: