前言

為什么在開發中，介面檔案越來越成為前后端開發人員溝通的樞紐呢？

隨著業務的發張，專案越來越多，而對于支撐整個專案架構體系而言，我們對系統業務的水平拆分，垂直分層，讓業務系統更加清晰，從而產生一系統平臺和系統，并使用介面進行資料互動，因此可見，業務的不斷發展，介面不斷增多，很多介面各自寄宿在不同的專案中，如果沒有使用api工具進行管理，那么使用和說明將變得非常復雜，所以，介面管理運營應運而生，

在過去的開發中，沒有API檔案管理工具之前，很多的API檔案在什么地方寫的都有，有在word寫的，有在excel寫的，也有對應的專案目錄下readme.md寫的，每個公司都有每個公司的玩法，但是檔案規范極其不統一，甚至出現開發介面更新，但檔案不更新，最終導致代碼和介面不匹配，開發功能出問題，擼碼一分鐘，對接三小時，這往往是大家最痛苦的，

因此，在前后端分離的情況下，怎樣讓前后端開發人員更容易、更直觀、更舒服的方式進行溝通交流，在這里，推薦一款輕量級的專案框架Swagger給大家使用，Swagger就是一款讓你更好書寫API檔案的框架

開始

一、參考Swagger的nuget包

Swashbuckle.AspNetCore

然后就在專案的Nuget依賴里看到剛剛引入的Swagger

二、服務配置環節

在Startup.cs頁面中：編輯 ConfigureServices 類：

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("V1", new OpenApiInfo
                {
                    Version = "V1",   //版本 
                    Title = $"XUnit.Core 介面檔案-NetCore3.1",  //標題
                    Description = $"XUnit.Core Http API v1",    //描述
                    Contact = new OpenApiContact { Name = "艾三元", Email = "", Url = new Uri("http://i3yuan.cnblogs.com") },  
                    License = new OpenApiLicense { Name = "艾三元許可證", Url = new Uri("http://i3yuan.cnblogs.com") }
                });
            });
            services.AddControllers();
        }

其中的Url地址不能為空，三、中間件啟動環節編輯Configure類注意：路徑配置，設定為空，表示直接在根域名（localhost:8001）訪問該檔案,注意localhost:8001/swagger是訪問不到的，去launchSettings.json把launchUrl去掉，如果你想換一個路徑，直接寫名字即可，比如直接寫c.RoutePrefix = "swagger";

        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }

            app.UseSwagger();
            app.UseSwaggerUI(c => {
                c.SwaggerEndpoint($"/swagger/V1/swagger.json", $"XUnit.Core V1");
                c.RoutePrefix = string.Empty;     //如果是為空 訪問路徑就為 根域名/index.html,注意localhost:8001/swagger是訪問不到的
                //路徑配置，設定為空，表示直接在根域名（localhost:8001）訪問該檔案
                // c.RoutePrefix = "swagger"; // 如果你想換一個路徑，直接寫名字即可，比如直接寫c.RoutePrefix = "swagger"; 則訪問路徑為 根域名/swagger/index.html
            });

            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }

到這里之后，我們已經完成了對swagger的添加，F5運行之后，

運行專案之后，我們發現官方默認的是 /WeatherForecast地址，所以我們修改成在域名后面輸入/index.html，就可以正常訪問了，

如果想修改默認的啟動地址，可以在launchSetting.json檔案中的launchUrl設定為空，或者洗掉掉就可以了，

這個時候我們再次啟動專案，就可以直接訪問根目錄下的檔案了，

如果啟動應用，并導航到 http://localhost:<port>/swagger/V1/swagger.json，生成的描述終結點的檔案顯示如下json格式，

補充

1. 已經有介面了，但如何添加注釋呢？ 2. 作為介面使用者，我們關心的是介面的回傳內容和回應型別，那我們如何定義描述回應型別呢？ 3. 在專案開發中，使用的物體類，又如何在Swagger中展示呢？ 4. 在部署專案，參考Swagger既有檔案又不需要額外部署，但是如何在開發環境中使用，而在生產環境中禁用呢？以上的這些內容，會在下一篇講解Swagger做Api檔案做詳解，好了，今天的使用Swagger做Api檔案上篇內容就說到這里了，希望能給大家在使用Core開發專案中使用Swagger生產介面檔案帶來幫助，

總結

1. 從過去手寫Api檔案，到引入Swagger工具自動生產API介面說明檔案，這一轉換，讓更多的介面可以以通俗易懂的方式展現給開發人員，

2. 后續會繼續介紹Swagger的一些高級用法，希望對大家使用Swagger有所幫助，

轉載請註明出處，本文鏈接：https://www.uj5u.com/net/54807.html

標籤：.NET Core

上一篇：.netcore2.1 統一介面回傳屬性名稱

下一篇：ASP.NET Core筆記(1) - 了解Startup類

基于.NetCore3.1系列 —— 使用Swagger做Api檔案 (上篇)

前言

開始

補充

總結