.Net Core3.0 WebApi 項目框架搭建：目錄

為什么使用Swagger

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

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

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

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

添加Swagger包

Nuget搜索Swashbuckle.AspNetCore

注冊Swagger服務

打開Startup.cs類，編輯 ConfigureServices 類

 public void ConfigureServices(IServiceCollection services)
        {
            var ApiName = "Webapi.Core";

            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("V1", new OpenApiInfo
                {
                    // {ApiName} 定義成全局變量，方便修改
                    Version = "V1",
                    Title = $"{ApiName} 接口文檔——Netcore 3.0",
                    Description = $"{ApiName} HTTP API V1",

                });
                c.OrderActionsBy(o => o.RelativePath);
            }
                services.AddControllers();
        }

wait，wait，wait，what？光一個注冊Swagger就這么多代碼？如果我再注冊其他的服務，豈不是讓ConfigureServices有N行代碼。。。。。。，雖然我們可以使用把代碼放在#region和#endregion里，但是如果可以將每個服務的配置,都封裝到一個方法里面，豈不美哉。如果我需要修改服務的配置代碼，只需要到對應的方法里面去修改，而不是去ConfigureServices這個方法里面找到需要修改的服務再去修改，而ConfigureServices里只需要services.addxxx()就行了，代碼簡約美觀直視。

原來還真有辦法，新建SetUp文件夾，存放要注冊的服務，我們新建一個靜態類SwaggerSetUp.cs,新建靜態方法AddSwaggerSetup，用來注冊Swagger

using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace Webapi.Core.SetUp
{
    public static class SwaggerSetUp
    {
        public static void AddSwaggerSetup(this IServiceCollection services)
        {
            if (services == null) throw new ArgumentNullException(nameof(services));

            var ApiName = "Webapi.Core";

            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("V1", new OpenApiInfo
                {
                    // {ApiName} 定義成全局變量，方便修改
                    Version = "V1",
                    Title = $"{ApiName} 接口文檔——Netcore 3.0",
                    Description = $"{ApiName} HTTP API V1",

                });
                c.OrderActionsBy(o => o.RelativePath);
            });

            }
    }
}

而我們的ConfigureServices只需要一句代碼就行了，是不是直觀了很多。

啟動Swagger

編輯Configure方法

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint($"/swagger/V1/swagger.json", "WebApi.Core V1");

                //路徑配置，設置為空，表示直接在根域名（localhost:8001）訪問該文件,注意localhost:8001/swagger是訪問不到的，去launchSettings.json把launchUrl去掉，如果你想換一個路徑，直接寫名字即可，比如直接寫c.RoutePrefix = "doc";
                c.RoutePrefix = "";
            });
            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllerRoute(
                        name: "default",
                        pattern: "{controller=Home}/{action=Index}/{id?}");
            });
        }

在 launchSettings.json 文件中的 launchUrl設置為空，或者刪掉。

F5啟動項目,直接訪問項目根目錄，當當當出來了：

what! No operations defined in spec!,

問題原因：我們將路由配置統一從 Controller中去掉然后 endpoints.MapControllerRoute設置了路由模版，由於Swagger無法在 Controller中找到 [Route("api/[controller]/[action]")]和 [ApiController]從而觸發了“No operations defined in spec!”的問題

解決方法:將 Startup.cs中 Configure里的路由模版注釋掉，改成 endpoints.MapControllers();，增加 BaseController.cs並繼承 ControllerBase，然后在 BaseController設置路由模版，讓 Controller繼承 BaseController

namespace Webapi.Core.Controllers
{
    /// <summary>
    /// 自定義路由模版
    /// 用於解決swagger文檔No operations defined in spec!問題
    /// </summary>
    [Route("api/[controller]/[action]")]
    [ApiController]
    public class BaseController : ControllerBase
    {
    }
}

UserController只需要繼承BaseController就行了

F5運行項目，能夠顯示了

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

但是現在有兩個問題：

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

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

添加接口注釋

右鍵項目名稱=>屬性=>生成，勾選“輸出”下面的“xml文檔文件”，這里我用的是相對路徑。

現在呢，配置好了xml文件，接下來需要讓系統啟動的時候，去讀取這個文件了，重新編輯SwaggerSetUp.cs，修改AddSwaggerSetup函數，注意配置的參數 true：

 services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("V1", new OpenApiInfo
                {
                    // {ApiName} 定義成全局變量，方便修改
                    Version = "V1",
                    Title = $"{ApiName} 接口文檔——Netcore 3.0",
                    Description = $"{ApiName} HTTP API V1",

                });
                c.OrderActionsBy(o => o.RelativePath);

                // 獲取xml注釋文件的目錄
                var xmlPath = Path.Combine(AppContext.BaseDirectory, "Webapi.Core.xml");
                c.IncludeXmlComments(xmlPath, true);//默認的第二個參數是false，這個是controller的注釋，記得修改
            });

給我們的控制器都加上注釋，F5運行項目，發現頁面注釋都加上了

添加Model注釋

新建一個.net core 類庫WebApi.Core.Model

新建實體類User

  /// <summary>
    /// 用戶表
    /// </summary>
    public class User
    {
        /// <summary>
        /// id
        /// </summary>
        public int Id { get; set; }
        /// <summary>
        /// 姓名
        /// </summary>
        public string Name { get; set; }
        /// <summary>
        /// 年齡
        /// </summary>
        public int Age { get; set; }
    }

右鍵項目屬性，生成 XML

編輯SwaggerSetUp.cs，修改AddSwaggerSetup函數，添加以下代碼

                var xmlModelPath = Path.Combine(AppContext.BaseDirectory, "Webapi.Core.Model.xml");//這個就是Model層的xml文件名
                c.IncludeXmlComments(xmlModelPath);

UserController新建一個Action

        /// <summary>
        /// 獲取User實體
        /// </summary>
        /// <param name="user"></param>
        /// <returns></returns>
        [HttpPost]
        public IActionResult User(User user)
        {
            return Ok(user);
        }