Net Core3.1 添加 Swagger

一、為什么使用Swagger

隨着互聯網技術的發展，現在的網站架構基本都由原來的后端渲染，變成了：前端渲染、后端分離的形態，而且前端技術和后端技術在各自的道路上越走越遠。 

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

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

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

二、配置Swagger服務

1、建一個net Core 3.1 的API項目，不演示了都會

2、引用Nuget包

右鍵項目中的 依賴項 -- > 管理 Nuget 程序包 --> 瀏覽 --> 搜索"Swashbuckle.AspNetCore" --> Install 安裝最新版 

 

安裝完成后在項目的Nuget依賴里看到剛剛引入的Swagger

 

 

 

 

3、配置服務

打開Startup.cs類，編輯ConfigureServices方法

// This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();

            #region swagger
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo { Title = "My API", Version = "v1" });
            });
            #endregion
        }

 

3、啟動Http中間件

編輯Configure方法

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            //判斷是否是環境變量
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }

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

            app.UseRouting();

            app.UseAuthorization();

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

 

4、查看效果

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

 

 

 

 

5、設置默認直接首頁訪問 —— 生產環境

每次手動在域名后邊輸入 /swagger ，很麻煩！ 

swagger 給我們提供了這個擴展，我們可以指定一個空字符，作為 swagger 的地址，在Configure中配置中間件：

           #region swagger 
            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");

                c.RoutePrefix = "";//路徑配置，設置為空，表示直接訪問該文件，表示直接在根域名（localhost:8001）訪問該文件
                //這個時候去launchSettings.json中把"launchUrl": "swagger/index.html"去掉， 然后直接訪問localhost:8001/index.html即可        
            });
            #endregion

然后再把我們上邊的項目文件 launchSettings.json 的 launchUrl 給去掉就行了，這樣我們無論是本地開發環境，還是生產環境，都可以默認首頁加載了。

 

這時候會發現沒有注釋，如果有注釋可讀性就很好了，下面開始實現注釋

6、顯示注釋

 1、給接口加一個注釋

        /// <summary>
        /// ID 獲取Json列表
        /// </summary>
        /// <param name="id"></param>
        /// <returns></returns>
        [HttpGet("{id}")]
        public IEnumerable<WeatherForecast> Get(int id)    

2、右鍵點擊項目---->屬性------>生成------>勾選xml文檔文件

 

 

3、在startup類中的ConfigureServices 方法中的服務集合中添加如下代碼

            #region swagger
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo { Title = "My API", Version = "v1" });
                
                var basePath = AppContext.BaseDirectory;

                var xmlPath = Path.Combine(basePath, "Blog.Core.xml");
                c.IncludeXmlComments(xmlPath, true); //添加控制器層注釋（true表示顯示控制器注釋）
            });
            #endregion

4、運行項目並訪問swaggerUI

 

 可以顯示注釋了

 

7、對 Model 也添加注釋說明

新建一個.net core 類庫Blog.Core.Model，注意是 .net core的類庫，或者使用標准庫也是可以的！（標准庫可以在 NetCore 和 Framework 兩個項目都可以跑）

 

 

然后新建一個model

    /// <summary>
    /// 這是愛
    /// </summary>
    public class Love
    {
        /// <summary>
        /// id
        /// </summary>
        public int Id { get; set; }
        /// <summary>
        /// 姓名
        /// </summary>
        public string Name { get; set; }
        /// <summary>
        /// 年齡
        /// </summary>
        public int Age { get; set; }
    }

1、當前 api 層直接引用了 Blog.Core.Model 層；

 

2、Blog.Core.Model 右鍵屬性配置 xml

 

 3、導入model.xml到swagger

// This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();

            #region swagger
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo { Title = "My API", Version = "v1" });
                
                var basePath = AppContext.BaseDirectory;

                var xmlPath = Path.Combine(basePath, "Blog.Core.xml");
                c.IncludeXmlComments(xmlPath, true); //添加控制器層注釋（true表示顯示控制器注釋）

                var xmlModelPath = Path.Combine(basePath, "Blog.Core.Model.xml");
                c.IncludeXmlComments(xmlModelPath, true);
            });
            #endregion
        }

 

接口添加注釋

        /// <summary>
        /// post
        /// </summary>
        /// <param name="love">model 實體類</param>
        [HttpPost]
        public void Post(Love love)
        { 
            
        }

重新運行就出來了

 

 

 

 

8、隱藏某些接口

如果不想顯示某些接口，直接在controller 上，或者action 上，增加特性

[ApiExplorerSettings(IgnoreApi = true)]

        /// <summary>
        /// post
        /// </summary>
        /// <param name="love">model 實體類</param>
        [HttpPost]
        [ApiExplorerSettings(IgnoreApi =true)]
        public void Post(Love love)
        { 
            
        }    

Post方法就不顯示了

 

 

三、結語

下一篇 Swagger JWT 權限，給接口加權限驗證