.Net core 使用swagger的注意事項

2019-09-03

本篇不會說明如何加入swagger到專案
而是介紹使用上實際遇到的問題處理

一般較大型的專案會使用專案分層
如果你的model是放在Model層或Common層
有寫summary註解但是開啟swagger可能會看不到屬性的描述
原因是swagger是去讀起始專案bin\Debug\netcoreapp2.2\ 底下的xml檔案
他不會把另外一層的class一起讀進來

原本寫法是這樣

services.AddSwaggerGen(c =>
        {
            var xmlPath = Path.Combine(AppContext.BaseDirectory, "專案名稱.Application.xml");

            c.IncludeXmlComments(xmlPath);
            c.SwaggerDoc(
                // name: 攸關 SwaggerDocument 的 URL 位置。
                name: "v1", 
                // info: 是用於 SwaggerDocument 版本資訊的顯示(內容非必填)。
                info: new Info
                {
                    Title = "RESTful API",
                    Version = "1.0.0",
                    Description = "This is ASP.NET Core RESTful API Sample.",
                    TermsOfService = "None",
                    Contact = new Contact { 
                        Name = "John Wu", 
                        Url = "https://blog.johnwu.cc" 
                    },
                    License = new License { 
                        Name = "CC BY-NC-SA 4.0", 
                        Url = "" 
                    }
                }
            );
        });

現在要把你的model所在的那一層的專案
右鍵>屬性>建置>勾選XML文件檔案
然後重新建置

就可以把xml檔讀到專案下
原本IncludeXmlComments的地方要改成

foreach (var name in Directory.GetFiles(AppDomain.CurrentDomain.BaseDirectory, "專案名稱.*.xml", SearchOption.AllDirectories))
                {
                    c.IncludeXmlComments(name);
                }

swagger參考文章:https://ithelp.ithome.com.tw/articles/10195190

回首頁