本文3.0版本文章

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

常見問題

1、Bug調試

群裡有小夥伴回報，在Swagger使用的時候報錯，無法看到清單，這裡我說下如何調試和主要問題：

1、如果遇到問題，這樣的：

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

請在浏覽器 =》 F12 ==》 console 控制台 ==》點選錯誤資訊位址

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

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

這是因為接口json文檔定義和調用不是一個

1、定義：

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

2、調用：

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

看看兩者是否一緻

3、路由重載

這種錯誤是因為路由過載了，請注意，是路由的過載，意思就是說，寫了兩個一樣的路由，進而導緻異常了，而不是說我們的方法一樣，舉例子：

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

這個時候我們就需要修改一下，要麼把謂詞不一樣，比如一個get，一個post，要麼修改路由規則 /api/[controller]/[action]。

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

一、為什麼使用Swagger

上文中已經說到，單純的項目接口在前後端開發人員使用是特别不舒服的，那所有要推薦一個，既友善又美觀的接口文檔說明架構，當當當，就是Swagger，随着網際網路技術的發展，現在的網站架構基本都由原來的後端渲染，變成了：前端渲染、後端分離的形态，而且前端技術和後端技術在各自的道路上越走越遠。

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

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

書寫API文檔的工具有很多，但是能稱之為“架構”的，估計也隻有swagger了。

二、配置Swagger服務

1、引用Nuget包

下面開始引入swagger插件

方法有兩個：

1）可以去swagger官網或github上下載下傳源碼，然後将源碼（一個類庫）引入自己的項目；

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

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

然後就在項目的Nuget依賴裡看到剛剛引入的Swagger

圖 2

這個時候，你可以試一下，當然是不可以的，還記得上文說的，.Net Core 都需要一個程式入口麼，對就是Startup.cs檔案

2、配置服務

打開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 = "[email protected]", Url = "https://www.jianshu.com/u/94102b59cc2a" }
                });
            });

            #endregion

        }

3、啟動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();
        }

4、檢視效果

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

5、好像少點兒什麼？！

在上邊的截圖中，我們可以看到，已經生成了一個 api 清單，我們不僅可以清晰的看到項目中含有那些接口，還可以直接點選發送請求，類似 postman 那樣，做接口調試，

但是現在有兩個問題：

1、這個接口文檔現在還不多，如果多了的話，每個接口對應的意義可能會混淆，

2、另外，這個接口文檔，也是友善前端工程師檢視的，目前這個這個樣式，看起來是挺費解的。

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

既美觀又快捷，而且還有豐富的注釋，這樣以後釋出出去，前後端開發人員就可以一起開發了，嗯！不錯！

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

三、結語

　　好啦，本節基本就是這裡了，你簡單浏覽後，會了解到，什麼是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();
        }

四、Github && Gitee

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

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

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