系列文章
一、前言
最近有空就優化 Jimu （一個基於.Net Core 的分布式微服務框架），考慮到現在的開發組織都向前后端分離發展，前后端各司其職，好的 api 文檔可以減少大家溝通的時間成本，所以優先給 Jimu 添加對 api 文檔生成的支持。市面上非常著名和牛逼的的 api 文檔生成框架非 swagger 莫屬。 它可以用來生成、描述、調用可視化的 Web 服務。花了 二天多的時間把它集成到 Jimu 的 apigateway。
如圖
api 列表
api 明細
二、使用方式
1. 環境
- Net Core 2.0
- 基於Jimu 框架的 ApiGateway
2. 添加引用
Install-Package Jimu.Client.ApiGateway.SwaggerIntegration
3. 啟動代碼
在 Startup 里添加 UseJimuSwagger()
public void ConfigureServices(IServiceCollection services)
{
services.UseJimuSwagger(); // 添加 Swagger 支持
}
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseJimuSwagger(); // 添加 Swagger 支持
4. 定義接口（服務/方法）
接口定義可以添加三種標注，這些標注最終會顯示在 swagger 生成的文檔。
a. JimuService 標注是對接口元數據的定義和描述，如創建人、時間、描述、訪問角色限制等。
b. JimuFieldComment 標注是對形式參數的注釋。
c. JimuReturnComment 標注是對接口的返回類型做注釋。
[JimuService(EnableAuthorization = true, CreatedBy = "grissom", CreatedDate = "2018-07-17", Comment = "根據新聞 id 獲取新聞內容")]
[JimuFieldComment("id", "新聞id")]
[JimuReturnComment("一篇新聞內容")]
News GetNews(string id);
5. 定義對象 (DTO)
如果接口參數或返回類型是一個用戶定義的類，對應的屬性也可以添加注釋標注 JimuFieldComment， 這些標注最終會顯示在 swagger 生成的文檔。
public class News
{
[JimuFieldComment("新聞id")]
public string Id { get; set; }
[JimuFieldComment("新聞標題")]
public string Title { get; set; }
[JimuFieldComment("作者")]
public string Director { get; set; }
[JimuFieldComment("發布時間")]
public string PostTime { get; set; }
[JimuFieldComment("新聞內容")]
public string Content { get; set; }
}
三、圖解
四、總結
支持開源是很累和很耗時間的活，不過開源過程中自己也學到很多知識，希望可以一直堅持下去。