基於.NetCore3.1系列 —— 使用Swagger作Api文檔 (上篇)

時間 2020-07-15

標籤基於 netcore3.1 netcore 系列使用 swagger api 文檔上篇简体版

原文原文鏈接

前言

爲何在開發中，接口文檔愈來愈成爲先後端開發人員溝通的樞紐呢？html

隨着業務的發張，項目愈來愈多，而對於支撐整個項目架構體系而言，咱們對系統業務的水平拆分，垂直分層，讓業務系統更加清晰，從而產生一系統平臺和系統，並使用接口進行數據交互。所以可見，業務的不斷髮展，接口不斷增多，不少接口各自寄宿在不一樣的項目中，若是沒有使用api工具進行管理，那麼使用和說明將變得很是複雜。因此，接口管理運營應運而生。json

在過去的開發中，沒有API文檔管理工具以前，不少的API文檔在什麼地方寫的都有，有在word寫的，有在excel寫的，也有對應的項目目錄下readme.md寫的，每一個公司都有每一個公司的玩法，可是文檔規範極其不統一，甚至出現開發接口更新，但文檔不更新，最終致使代碼和接口不匹配，開發功能出問題。擼碼一分鐘，對接三小時。這每每是你們最痛苦的。後端

所以，在先後端分離的狀況下，怎樣讓先後端開發人員更容易、更直觀、更舒服的方式進行溝通交流。在這裏，推薦一款輕量級的項目框架Swagger給你們使用。Swagger就是一款讓你更好書寫API文檔的框架api

開始

1、引用Swagger的nuget包架構

Swashbuckle.AspNetCoreapp

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

2、服務配置環節前後端分離

在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地址不能爲空。

3、中間件啓動環節

編輯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();
            });
        }