Swagger Open API 初嘗試

2022-04-02 置頂文章

241
0
Swagger

開發API。若可以同時產生文件，則可減少工作內容，所以本次嘗試使用Swagger，看看該工具可以有什麼樣的幫助

環境

VS2022
ASP.NET Core 6

建立專案

點選專案屬性並勾選文件檔案

隱藏警告中填入

$(NoWarn);1591

如無填入，則會出現警告要求寫入Summary

打開專案的Csproj檔，可看到剛勾選的屬性已寫入Csproj

打開Program檔找到

builder.Services.AddSwaggerGen()

修改為

builder.Services.AddSwaggerGen(options =>
{
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    options.IncludeXmlComments(xmlPath, true);
});

Controllers加上Summary，以及Produces限制回應Json格式

執行並驗證

點開Get

點擊Try it out

執行後建置的路徑多一個Xml

良好的編寫Summary此時就成了API文件的產生幫手，而文件則成了公開的URL，或是可以轉Swagger JSON提供給對方使用

以上為初次簡易嘗試，後續會再提供進階需要使用到的功能

回首頁