從壹開始先後端分離【 .NET Core2.0/3.0 +Vue2.0 】框架之三 || Swagger的使用 3.1

本文3.0版本文章

https://mp.weixin.qq.com/s/SHNNQoYF-t8i2j85E1oSYA

 

 

常見問題

 

一、Bug調試

羣裏有小夥伴反饋，在Swagger使用的時候報錯，沒法看到列表，這裏我說下如何調試和主要問題：

一、若是遇到問題，這樣的：

 

請在瀏覽器 =》 F12 ==》 console 控制檯 ==》點擊錯誤信息地址

或者直接連接http://localhost:xxxxx/swagger/v1/swagger.json，就能看到錯誤了

 

 

二、常常有小夥伴遇到這個錯誤

 

 

這是由於接口json文檔定義和調用不是一個

一、定義：

ConfigureServices 方法中的  services.AddSwaggerGen 註冊的一個名字 c.SwaggerDoc("v1", 

二、調用：

Configure 方法中的 app.UseSwaggerUI(c =>   調用  c.SwaggerEndpoint("/swagger/v1/swagger.js；

看看二者是否一致

 

 

三、路由重載

 

 

這種錯誤是由於路由過載了，請注意，是路由的過載，意思就是說，寫了兩個同樣的路由，從而致使異常了，而不是說咱們的方法同樣，舉例子：

可能你在 valuecontroller 裏寫了一個  Test1() 和 Test2() ，雖然方法名不同，可是若是你的路由規範是 /api/[controller] 的話，那映射出來的路由，兩個都是 api/value ，因此就會報過載異常，

這個時候咱們就須要修改一下，要麼把謂詞不同，好比一個get，一個post，要麼修改路由規則 /api/[controller]/[action]。

詳細的知識點，請看官網。

 

 

 

---

1、爲何使用Swagger

上文中已經說到，單純的項目接口在先後端開發人員使用是特別不舒服的，那全部要推薦一個，既方便又美觀的接口文檔說明框架，噹噹噹，就是Swagger，隨着互聯網技術的發展，如今的網站架構基本都由原來的後端渲染，變成了：前端渲染、後端分離的形態，並且前端技術和後端技術在各自的道路上越走越遠。 

前端和後端的惟一聯繫，變成了API接口；API文檔變成了先後端開發人員聯繫的紐帶，變得愈來愈重要，swagger就是一款讓你更好的書寫API文檔的框架。

沒有API文檔工具以前，你們都是手寫API文檔的，在什麼地方書寫的都有，有在confluence上寫的，有在對應的項目目錄下readme.md上寫的，每一個公司都有每一個公司的玩法，無所謂好壞。

書寫API文檔的工具備不少，可是能稱之爲「框架」的，估計也只有swagger了。 

 

2、配置Swagger服務

一、引用Nuget包

下面開始引入swagger插件

方法有兩個：

1）能夠去swagger官網或github上下載源碼，而後將源碼（一個類庫）引入本身的項目；

2）直接利用NuGet包添加程序集應用（這裏就是前邊說的 在之後的開發中，Nuget無處不在）。

右鍵項目中的 Dependencies -- > Manage Nuget Packags --> Browse --> Search "Swashbuckle.AspNetCore" --> Install

 

 

而後就在項目的Nuget依賴裏看到剛剛引入的Swagger

 

圖 2

這個時候，你能夠試一下，固然是不能夠的，還記得上文說的，.Net Core 都須要一個程序入口麼，對就是Startup.cs文件

 

二、配置服務

打開Startup.cs類，編輯ConfigureServices類

　　　　 public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc();

            #region Swagger
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info
                {
                    Version = "v0.1.0",
                    Title = "Blog.Core API",
                    Description = "框架說明文檔",
                    TermsOfService = "None",
                    Contact = new Swashbuckle.AspNetCore.Swagger.Contact { Name = "Blog.Core", Email = "Blog.Core@xxx.com", Url = "https://www.jianshu.com/u/94102b59cc2a" }
                });
            });

            #endregion

        }

 

三、啓動Http中間件

編輯Configure類

    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }

            #region Swagger
            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "ApiHelp V1");
            });
            #endregion

            app.UseMvc();
        }

 

四、查看效果

到這，已經完成swagger的添加，F5 運行調試，在域名後面輸入/swagger，http://localhost:54067/swagger/index.html 點擊回車，噹噹噹 出來啦

 

五、好像少點兒什麼？！

 

在上邊的截圖中，咱們能夠看到，已經生成了一個 api 列表，咱們不只能夠清晰的看到項目中含有那些接口，還能夠直接點擊發送請求，相似 postman 那樣，作接口調試，

可是如今有兩個問題：

一、這個接口文檔如今還很少，若是多了的話，每一個接口對應的意義可能會混淆，

二、另外，這個接口文檔，也是方便前端工程師查看的，目前這個這個樣式，看起來是挺費解的。

 

這個時候，要是有一個註釋功能就很好了，彆着急，看看下邊的截圖，是否是你想要的效果？！

 

既美觀又快捷，並且還有豐富的註釋，這樣之後發佈出去，先後端開發人員就能夠一塊兒開發了，嗯！不錯！

那這個註釋功能，應該這麼作呢？下一篇文章就會說到了。

 

3、結語

　　好啦，本節基本就是這裏了，你簡單瀏覽後，會了解到，什麼是Swagger，它如何建立使用，如何運行的，可是，細心的你會發現一些問題：

如何直接F5運行，首頁沒法加載？

接口雖有，可是沒有文字文檔說明？

對於接口是如何加權限驗證的？

如何發佈到服務器，你們一塊兒接口開發呢？

項目開發中的實體類是如何在Swagger中展現的？

讓咱們帶着這些問題，繼續瀏覽下一篇吧，Swagger 3.2 配置

ღ 網友反饋ღ

@BlueDr提出：能夠將Swagger的UI頁面配置在Configure的開發環境之中

       public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
                #region Swagger
                app.UseSwagger();
                app.UseSwaggerUI(c =>
                {
                    c.SwaggerEndpoint("/swagger/v1/swagger.json", "ApiHelp V1");
                });
                #endregion
            }


            app.UseMvc();
        }

 

 

4、Github && Gitee

https://github.com/anjoy8/Blog.Core.git

https://gitee.com/laozhangIsPhi/Blog.Core