基于dotNET 5 MVC經典模式引入Swagger進行web api開發(fā)和管理發(fā)布OAS3標準接口文檔全過程

title: 基于dotNET 5 MVC經典模式引入Swagger進行web api開發(fā)和管理發(fā)布OAS3標準接口文檔全過程
date: 2021-06-24
sidebarDepth: 2
tags:

  • dotNET5
  • MVC
  • swagger
  • OAS3
    categories:
  • cms
  • 微軟技術
  • 安全

Swagger 是一個規(guī)范且完整的框架，用于生成、描述、調用和可視化 RESTful 風格的 Web 服務。
Swagger 的目標是對 REST API 定義一個標準且和語言無關的接口，可以讓人和計算機擁有無需訪問源碼、文檔或網絡流量監(jiān)測就可以發(fā)現(xiàn)和理解服務的能力。當通過 Swagger 進行正確定義，用戶可以理解遠程服務并使用最少實現(xiàn)邏輯與遠程服務進行交互。與為底層編程所實現(xiàn)的接口類似，Swagger 消除了調用服務時可能會有的猜測。

面向web api開發(fā)

大家在開發(fā)完 webapi 后，經常為了方便接口雙方對接，需要將 webapi 接口文檔化，那有沒有什么快捷可交互的文檔呢？可以利用快捷工具 Swagger，它的可視化 UI 可輕松助你 API 文檔化的同時還方便測試 API。

Swashbuckle 就是一個用于生成 Swagger 文檔的開源工具包，這篇文章將會討論如何利用 Swashbuckle 來為你的 Restful API 生成可交互的文檔。

什么是Swagger

Swagger 是一個規(guī)范且完整的框架，用于生成、描述、調用和可視化 RESTful 風格的 Web 服務。
Swagger 的目標是對 REST API 定義一個標準且和語言無關的接口，可以讓人和計算機擁有無需訪問源碼、文檔或網絡流量監(jiān)測就可以發(fā)現(xiàn)和理解服務的能力。當通過 Swagger 進行正確定義，用戶可以理解遠程服務并使用最少實現(xiàn)邏輯與遠程服務進行交互。與為底層編程所實現(xiàn)的接口類似，Swagger 消除了調用服務時可能會有的猜測。

Swagger 的優(yōu)勢

  • 支持 API 自動生成同步的在線文檔：使用 Swagger 后者可以直接通過代碼生成文檔，不再需要自己手動編寫接口文檔了，對程序員來說非常方便，可以節(jié)約寫文檔的時間去學習新技術。
  • 提供 Web 頁面在線測試 API：光有文檔還不夠，Swagger 生成的文檔還支持在線測試。參數(shù)和格式都定好了，直接在界面上輸入參數(shù)對應的值即可在線測試接口。

說白了就是一種接口文檔，而且支持在線調試，從而提升web api開發(fā)的效率。
其它同類型的工具還有apidoc,如：https://code.z01.com/apidoc/ 就是用apidoc生成，可以檢索、遍歷，缺點是不能調試。
來自Java開源社區(qū)的Swagger則功能更加強大，自然受人歡迎。

一句話：
*** dotNET CORE Swagger的使用，寫好注釋就是寫好接口文檔***

其運界面如下所示：


圖片名稱

什么是OAS3

作為一個經常要提供給API文檔給內部和第三方的閱讀的“苦程”，我一直在尋找一個完美的Spring MVC文檔解決方案。過去，我一直使用的是springfox-swagger2依賴，使用swagger2注解，對代碼進行注釋，生成swagger文檔。 不過，早在2020年Swagger2就已過時，springfox-swagger2也已停止維護。業(yè)界普遍轉向了OAS3 規(guī)范管理文檔接口，這也是當前OpenApi規(guī)范標準。

在dotNet Core和dotNET 5的web api項目中引入Swagger

注意：這里是web api 項目，在vs 2019中創(chuàng)建項目如下：


圖片名稱

1、新建一個asp.net core web api項目

圖片名稱

圖片名稱

2、Nuget安裝Swagger

圖片名稱

3、為接口及接口中用到的類添加注釋

圖片名稱

圖片名稱

4、右鍵項目屬性（如果項目中有其他庫的，都需要參照配置下）生成XML文檔，如下圖打勾保存

圖片名稱

5、Startup配置Swagger，這里用到了一個自定義的擴展類：

SwaggerHttpHeaderOperation，這個類里面增加了調試的Http請求header參數(shù)，比如Token就可以擴展下，這樣在調試時就可以填寫該參數(shù)，方便調試需要鑒權的接口。

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using System;
using System.IO;
using System.Text;

namespace ZQSwaggerDemo
{
    public class Startup
    {
        const string PROJECTNAME = "知擎物聯(lián)API";
        const string VERSION = "v1.0.0";

        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();
            //配置swagger
            StringBuilder fDescription = new StringBuilder();
            fDescription.Append("<a target='_blank'  class='link'>常州知擎物聯(lián)科技有限公司 版權所有</a>");
            fDescription.Append($"<br>API適用標注說明：");
            fDescription.Append($"<br><span style='color:blue'>【NOTOKEN】</span>：無需登錄可訪問");
            services.AddSwaggerGen(c =>
            {
                c.OperationFilter<SwaggerHttpHeaderOperation>();

                c.SwaggerDoc(VERSION, new Microsoft.OpenApi.Models.OpenApiInfo()
                {
                    Title = PROJECTNAME,
                    Version = VERSION,
                    Description = ""
                }); ;
                //加載注釋xml文件（這里演示的代碼是為了方便一次性加載多個XML文檔，省去了一個個XML文件添加的繁瑣）
                string[] files = Directory.GetFiles(AppDomain.CurrentDomain.BaseDirectory, "ZQ*.xml");
                foreach (string item in files)
                {
                    c.IncludeXmlComments(item);
                }
            });
        }

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            app.UseSwagger();//啟用中間件服務生成Swagger作為JSON終結點
            app.UseSwaggerUI(c =>
            {
                //啟用中間件服務對swagger-ui，指定Swagger JSON終結點
                c.SwaggerEndpoint($"/swagger/{VERSION}/swagger.json", PROJECTNAME);
            });
            app.UseRouting();

            app.UseAuthorization();

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

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;

namespace ZQSwaggerDemo
{
    /// <summary>
    /// Swagger調試header
    /// </summary>
    public class SwaggerHttpHeaderOperation : IOperationFilter
    {
        /// <summary>
        /// 
        /// </summary>
        /// <param name="operation"></param>
        /// <param name="context"></param>
        public void Apply(OpenApiOperation operation, OperationFilterContext context)
        {
            operation.Parameters.Add(new OpenApiParameter()
            {
                Name = "Token",
                In = ParameterLocation.Header,
                Required = false,
                Schema = new OpenApiSchema { Type = "string" }
            });
        }
    }
}

6、啟動項目，訪問：

http://localhost:45039/swagger/index.html 可以看到之前寫的注釋都在文檔中體現(xiàn)了出來

圖片名稱

7、調試接口

對想要調試的接口，展開接口后，點擊Try it out按鈕，這里我們可以看到之前擴展的Header部分參數(shù)（本DEMO僅示范，并未使用，實際項目中還是經常需要自定義一些header參數(shù)），填寫好參數(shù)后，點擊Execute調用接口，可以看到成功返回了數(shù)據。

圖片名稱

圖片名稱

在dotNet Core和dotNET 5的MVC項目中引入Swagger

上面的一節(jié)，我們介紹了在web api項目中引入swagger，但大多數(shù)項目不是web api項目，而是經典的mvc項目，要如何應用呢？
別急，這里開始分享全過程。

一.新建項目： dotnet new mvc -n SwaggerTest

圖片名稱

二.添加nuget引用 ：dotnet add TodoApi.csproj package Swashbuckle.AspNetCore -v 5.0.0

也可以使用 Package Manager Console

圖片名稱

三.Startup中的ConfigureServices 添加服務

services.AddSwaggerGen(c =>
          {
              c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo { Title = "Docs", Version = "V1" });
          });
圖片名稱

四.在Startup中的Configure使用 代碼如下

app.UseSwagger();
app.UseSwaggerUI(c=>c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"));
圖片名稱

五.在HomeController添加如下代碼

public class HomeController : Controller
{
    /// <param name="name"></param>        
    [HttpPost("{name}")]
    public IActionResult Find(string name)
    {
        if (string.IsNullOrWhiteSpace(name)) return NotFound();
        else return Content(name);
    }
}

六.測試

圖片名稱

圖片名稱

如果上面文檔不足，還要可以補充看下面的：

安裝 Swagger 中間件

要想利用 Swagger 文檔化，需要 nuget 引用 Swashbuckle.AspNetCore 包，還可以通過 Visual Studio 2019 的 NuGet package manager 可視化界面安裝 或者 通過 NuGet package manager 命令行工具輸入以下命令：

dotnet add package Swashbuckle.AspNetCore

配置 Swagger 中間件

為了配置 Swagger，在 Startup.ConfigureServices 方法中添加如下代碼，注意下面的 AddSwaggerGen 方法是用于給 API 文檔 添加一些元數(shù)據。


  services.AddSwaggerGen(c =>;
  {
      c.SwaggerDoc("v1", new Info
      {
          Version = "v1",
          Title = "Swagger Demo",
          Description = "Swagger Demo for ValuesController",
          TermsOfService = "None",
          Contact = new Contact() { Name = "Joydip Kanjilal",
          Email = "joydipkanjilal@yahoo.com",
          Url = "www.google.com" }
      });
  });

接下來就要啟動 Swagger了，在 Startup.Configure 方法下添加如下代碼：

  app.UseSwagger();
  app.UseSwaggerUI(c =&gt;
  {
      c.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
  });

為了完整性，下面是 Startup 中的所有代碼清單。

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Swashbuckle.AspNetCore.Swagger;
namespace IDGSwaggerDemo
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }
        public IConfiguration Configuration { get; }
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc().SetCompatibilityVersion
            (CompatibilityVersion.Version_2_2);   
            services.AddSwaggerGen(c =&gt;
            {
                c.SwaggerDoc("v1", new Info
                {
                    Version = "v1",
                    Title = "Swagger Demo",
                    Description = "Swagger Demo for ValuesController",
                    TermsOfService = "None",
                    Contact = new Contact() { Name = "Joydip Kanjilal",
                    Email = "joydipkanjilal@yahoo.com",
                    Url = "www.google.com"
                }
                });
            });
        }
        public void Configure(IApplicationBuilder app,
       IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            app.UseMvc();
            app.UseSwagger();
            app.UseSwaggerUI(c =&gt;
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
            });
        }
    }
}

瀏覽 Swagger UI

現(xiàn)在我們運行一下應用程序來瀏覽一下 Swagger UI 地址，可以看到 UI 界面如下圖所示，圖中不同的 Http 請求使用了不同的顏色進行標識，你甚至可以在UI上直接測試不同的 api 接口。

圖片名稱

在 Action 方法上創(chuàng)建xml注解

到目前為止一切順利，在剛才生成的 swagger 文檔中，并沒有看到 5 個 api 接口的任何注解，這就不優(yōu)雅了，如果想要在 swagger 文檔上增加 xml 注解，簡單粗暴的做法可以直接在 Controller.Action 頂部寫上注解信息。

接下來在 ValuesController 下的每一個 Action 上都加上注解，下面就是修改后的 ValueController。

    [Route("api/[controller]")]
    [ApiController]
    public class ValuesController : ControllerBase
    {
        /// 
        /// Get action method without any argument
        /// 
        /// 
        [HttpGet]
        public ActionResult&gt; Get()
        {
            return new string[] { "value1", "value2" };
        }

        /// 
        /// Get action method that accepts an integer as an argument
        /// 
        /// 
        /// 
        [HttpGet("{id}")]
        public ActionResult Get(int id)
        {
            return "value";
        }

        /// 
        /// Post action method to add data
        /// 
        /// 
        [HttpPost]
        public void Post([FromBody] string value)
        {
        }

        /// 
        /// Put action method to modify data
        /// 
        /// 
        /// 
        [HttpPut("{id}")]
        public void Put(int id, [FromBody] string value)
        {
        }

        /// 
        /// Delete action method
        /// 
        /// 
        [HttpDelete("{id}")]
        public void Delete(int id)
        {
        }
    }

打開 xml 注解

值得注意的是： Swagger 默認并不會顯示 XML 注解，需要手工打開它，那怎么做呢？右鍵 Project，選擇 Properties 后切換到 Build 頁面，然后選中 XML documentation file 項 并且指定好 xml 生成的位置，參考如下：

圖片名稱

接下來還要在 ConfigureServices 方法下將生成xml 的路徑配置到 swagger 中，如下代碼所示：

c.IncludeXmlComments(@"D:\Projects\IDG\IDGSwaggerDemo\IDGSwaggerDemo\IDGSwaggerDemo.xml");

這就是打開 Swagger 中的 xml 注解 所需的所有事情。

指定啟動url 到 Swagger UI

要想將啟動項目的url指到 SwaggerUI，右鍵 Project 并選擇 Properties，在 Debug 的 Lanuch browser 上指定 swagger 即可，如下圖所示：

圖片名稱

再次運行程序可以發(fā)現(xiàn)默認頁就是 Swagger URL 了，如下圖所示：

圖片名稱

從圖中可以看到，5個API方法后面都有相應的 xml 注解了。

Swashbuckle 是一個非常好的工具，可以簡單粗暴的給 API接口生成文檔，從文中也可以看出 Swashbuckle 的配置非常簡單，Swagger 還有一些更高級的功能，比如通過 CSS 來定制 Swagger UI，還可以根據API的版本生成不同的 Swagger 文

注解格式

尋找[Route(代碼，定義為[HttpGet]或[HttpPost]：

/// <summary>
/// 全局錯誤提示
/// </summary>
/// <remarks>用于系統(tǒng)的錯誤頁提示返回信息。</remarks>
/// <returns>成功返回！</returns>
/// <param name="code">錯誤代碼</param>
/// <returns></returns>
[Route("Common/Error/{code}")]
[HttpGet]
public IActionResult Error(int code)
{
    //int code = DataConvert.CLng(GetParam("code"));
    ViewBag.statusCode = code;
    return View("~/Views/Shared/Prompt/statusCode.cshtml");
}
圖片名稱

圖片名稱

相關資料

?著作權歸作者所有,轉載或內容合作請聯(lián)系作者
【社區(qū)內容提示】社區(qū)部分內容疑似由AI輔助生成，瀏覽時請結合常識與多方信息審慎甄別。
平臺聲明：文章內容（如有圖片或視頻亦包括在內）由作者上傳并發(fā)布，文章內容僅代表作者本人觀點，簡書系信息發(fā)布平臺，僅提供信息存儲服務。

相關閱讀更多精彩內容

友情鏈接更多精彩內容