微服務系列之Api文檔 swagger整合
1.前言
微服務架構隨之而來的前後端徹底分離，且服務眾多，無論是前後端對接亦或是產品、運營翻看，一個現代化、規範化、可視化、可嘗試的文檔是多麼重要，所以我們這節就說說swagger。
Swagger是一款RESTFUL介面的文檔在線自動生成+功能測試功能軟體。Swagger是一個規範和完整的框架,用於生成、描述、調用和可視化RESTful風格的Web服務。目標是使客戶端和文件系統作為伺服器以同樣的速度來更新文件的方法,參數和模型緊密集成到伺服器。
swagger優勢:
1)後端開發人員，不在重複的用wiki或word不斷改來改去;
2).net core集成簡單，無侵入性，開發人員只需要使用.net自身的注釋即可;
2.實戰
新建一個.net core3.1項目,nuget安裝Swashbuckle.AspNetCore包最新版本
DI注入
services.AddSwaggerGen(e => { e.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo() { Title = "MySwaggerService1 API",//文檔標題 Version = "v1"//文檔版本 } ); //e.OperationFilter<AddAuthTokenFilter>(); e.IncludeXmlComments(System.IO.Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "MySwaggerService1.xml"));//swagger會自動生成文檔xml文件，指定位置來載入 //e.IncludeXmlComments(System.IO.Path.Combine(Microsoft.Extensions.PlatformAbstractions.PlatformServices.Default.Application.ApplicationBasePath, "xxxxx.xml"));//注釋的這裡，swagger會為每個類庫都生成類庫名.xml的配置文件，我這裡只有一個簡單的demo,所以不用 });
添加中間件
app.UseSwagger() .UseSwaggerUI(c => { c.SwaggerEndpoint($"/swagger/v1/swagger.json", "MySwaggerService1"); });
項目右鍵屬性=》生成，將debug和release配置下，輸出=》輸出路徑=》xml文檔位置,勾選，默認即可。
寫一個get介面，寫一個post介面。
[Route("api/[controller]")] [ApiController] public class DemoController : ControllerBase { /// <summary> /// 我的介面 /// </summary> /// <param name="no">我的參數</param> /// <returns></returns> [ProducesResponseType(typeof(string), (int)HttpStatusCode.OK)] [ProducesResponseType(typeof(string), (int)HttpStatusCode.BadRequest)] [HttpGet("my")] public async Task<IActionResult> My([FromQuery] string no) { return Ok("hello docker"); } /// <summary> /// 我的第二個介面 /// </summary> /// <param name="queryModel"></param> /// <returns></returns> [ProducesResponseType(typeof(List<MyViewModel>), (int)HttpStatusCode.OK)] [ProducesResponseType(typeof(string), (int)HttpStatusCode.BadRequest)] [HttpPost("query/my")] public async Task<IActionResult> PostMy([FromBody] MyQueryModel queryModel) { var res = new List<MyViewModel>(); res.Add(new MyViewModel() { Gid = "1", MyList = new List<int>() { 1,2,3} }); return Ok(res); } }
啟動後：地址 //localhost:xxxx/swagger.
到此，.net core集成swagger結束。
3.swagger切換
上文這個服務的在線文檔已經好了，如果10個服務的話，想要查看，就要打開10個地址，而微服務系統可遠不止10個那麼少，所以我們要用一個統一地址，可以選擇服務進行自由切換。配置如下:
我們已經建立了一個服務，並且配置好了swagger,我們在新建一個一樣的服務，並且一樣配置好swagger，並且寫2個介面
再新建一個服務，做為swagger統一入口服務，一樣引入nuget包，DI注入也是一樣的，只需要在添加中間件的時候利用swagger的SwaggerUIOptions的擴展SwaggerEndpoint，就可以集中配置，如程式碼
var apis = new List<string>(); apis.Add("//localhost:5001"); apis.Add("//localhost:5002"); app.UseSwagger() .UseSwaggerUI(c => { apis.ForEach(m => { c.SwaggerEndpoint($"{m}/swagger/v1/swagger.json", m); }); });
然後，三個服務同時啟動，打開這個統一文檔服務的swagger地址如下圖：
看右上角，可以切換服務定義了，這回方便了。回到統一服務的，中間件配置的程式碼上，因為人家是endpoint，是地址，所以我們只能如此簡陋的配置，在切換地方顯示的是地址，真實項目中，這樣肯定不行的，首先開發人員要知道所有服務地址是不顯示的，其次通過地址切換，你也不知道服務是幹啥的，所以實際項目中，我們是利用網關+consul+配置中心的地址規則，來集中配置。如下圖
最後的統一文檔服務的目標切換，就是服務名稱
全文結束。。
