這篇文章將為大家詳細講解有關(guān).NET Core怎么利用swagger進行API接口文檔管理，小編覺得挺實用的，因此分享給大家做個參考，希望大家閱讀完這篇文章后可以有所收獲。

10年積累的做網(wǎng)站、網(wǎng)站設(shè)計經(jīng)驗，可以快速應(yīng)對客戶對網(wǎng)站的新想法和需求。提供各種問題對應(yīng)的解決方案。讓選擇我們的客戶得到更好、更有力的網(wǎng)絡(luò)服務(wù)。我雖然不認識你，你也不認識我。但先網(wǎng)站制作后付款的網(wǎng)站建設(shè)流程，更有趙縣免費網(wǎng)站建設(shè)讓你可以放心的選擇與我們合作。

一、問題背景

隨著技術(shù)的發(fā)展，現(xiàn)在的開發(fā)模式已經(jīng)更多的轉(zhuǎn)向了前后端分離的模式，在前后端開發(fā)的過程中，聯(lián)系的方式也變成了API接口，但是目前項目中對于API的管理很多時候還是通過手工編寫文檔，每次的需求變更只要涉及到接口的變更，文檔都需要進行額外的維護，如果有哪個小伙伴忘記維護，很多時候就會造成一連續(xù)的問題，那如何可以更方便的解決API的溝通問題？Swagger給我們提供了一個方式，由于目前主要我是投入在.NET Core項目的開發(fā)中，所以以.NET Core作為示例

二、什么是Swagger

Swagger可以從不同的代碼中，根據(jù)注釋生成API信息，swagger擁有強大的社區(qū)，并且對于各種語言都支持良好，有很多的工具可以通過swagger生成的文件生成API文檔

三、.NET Core中使用

.NET Core中使用首先要用nuget引用Swashbuckle.AspNetCore，在startup.cs中加入如下代碼

  // This method gets called by the runtime. Use this method to add services to the container.
  public void ConfigureServices(IServiceCollection services)
  {
   services.AddMvc();
   services.AddSwaggerGen(c =>
   {
    c.SwaggerDoc("v1", new Info { Title = "Hello", Version = "v1" });
    var basePath = PlatformServices.Default.Application.ApplicationBasePath;
    var xmlPath = Path.Combine(basePath, "WebApplication2.xml");
    c.IncludeXmlComments(xmlPath);
   });
   services.AddMvcCore().AddApiExplorer();
  }
  // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
  public void Configure(IApplicationBuilder app, IHostingEnvironment env)
  {
   if (env.IsDevelopment())
   {
    app.UseDeveloperExceptionPage();
   }
   app.UseMvcWithDefaultRoute();
   app.UseSwagger(c =>
   {
   });
   app.UseSwaggerUI(c =>
   {
    c.ShowExtensions();
    c.ValidatorUrl(null);
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "test V1");
   });
  }

以上部分為加載swagger的代碼，位于startup.cs中，下面是controller代碼：

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
namespace WebApplication2.Controllers
{
 /// <summary>
 /// 測試信息
 /// </summary>
 [Route("api/[controller]/[action]")]
 public class ValuesController : Controller
 {
  /// <summary>
  /// 獲取所有信息
  /// </summary>
  /// <returns></returns>
  [HttpGet]
  public IEnumerable<string> Get()
  {
   return new string[] { "value1", "value2" };
  }
  /// <summary>
  /// 根據(jù)ID獲取信息
  /// </summary>
  /// <param name="id"></param>
  /// <returns></returns>
  // GET api/values/5
  [HttpGet("{id}")]
  public string Get(int id)
  {
   return "value";
  }
  /// <summary>
  /// POST了一個數(shù)據(jù)信息
  /// </summary>
  /// <param name="value"></param>
  // POST api/values
  [HttpPost]
  public void Post([FromBody]string value)
  {
  }
  /// <summary>
  /// 根據(jù)ID put 數(shù)據(jù)
  /// </summary>
  /// <param name="id"></param>
  /// <param name="value"></param>
  // PUT api/values/5
  [HttpPut("{id}")]
  public void Put(int id, [FromBody]string value)
  {
  }
  /// <summary>
  /// 根據(jù)ID刪除數(shù)據(jù)
  /// </summary>
  /// <param name="id"></param>
  // DELETE api/values/5
  [HttpDelete("{id}")]
  public void Delete(int id)
  {
  }
  /// <summary>
  /// 復(fù)雜數(shù)據(jù)操作
  /// </summary>
  /// <param name="id"></param>
  // DELETE api/values/5
  [HttpPost]
  public namevalue test(namevalue _info)
  {
   return _info;
  }
 }

 public class namevalue
 {
  /// <summary>
  /// name的信息
  /// </summary>
  public String name { get; set; }
  /// <summary>
  /// value的信息
  /// </summary>
  public String value { get; set; }
 }
}

接下來我們還需要在生成中勾上XML生成文檔，如圖所示

接下去我們可以運行起來了，調(diào)試，瀏覽器中輸入http://localhost:50510/swagger/，這里端口啥的根據(jù)實際情況來，運行效果如下圖所示：

可以看到swagger將方法上的注釋以及實體的注釋都抓出來了，并且顯示在swaggerui，整體一目了然，并且可以通過try it按鈕進行簡單的調(diào)試，但是在具體項目中，可能存在需要將某些客戶端信息通過header帶到服務(wù)中，例如token信息，用戶信息等（我們項目中就需要header中帶上token傳遞到后端），那針對于這種情況要如何實現(xiàn)呢？可以看下面的做法

// This method gets called by the runtime. Use this method to add services to the container.
  public void ConfigureServices(IServiceCollection services)
  {
   services.AddMvc();
   services.AddSwaggerGen(c =>
   {
    c.SwaggerDoc("v1", new Info { Title = "Hello", Version = "v1" });
    var basePath = PlatformServices.Default.Application.ApplicationBasePath;
    var xmlPath = Path.Combine(basePath, "WebApplication2.xml");
    c.IncludeXmlComments(xmlPath);
    c.OperationFilter<AddAuthTokenHeaderParameter>();
   });
   services.AddMvcCore().AddApiExplorer();
  }

 public class AddAuthTokenHeaderParameter : IOperationFilter
 {
  public void Apply(Operation operation, OperationFilterContext context)
  {
   if (operation.Parameters == null)
   {
    operation.Parameters = new List<IParameter>();
   }
   operation.Parameters.Add(new NonBodyParameter()
   {
    Name = "token",
    In = "header",
    Type = "string",
    Description = "token認證信息",
    Required = true
   });
  }
 }

我們在ConfigureServices添加了OperationFilter<AddAuthTokenHeaderParameter>()，通過這種方式我們可以在swagger中顯示token的header，并且進行調(diào)試（如圖所示），AddAuthTokenHeaderParameter 的apply的屬性context中帶了controller以及action的各種信息，可以配合實際情況使用

 四、與其他API管理工具結(jié)合

swagger強大的功能以及社區(qū)的力量，目前很多的API管理工具都支持YApi，目前我們使用的是由去哪兒開源的YApi，從圖中可以看到Y(jié)Api支持導(dǎo)入swagger生成的JSON文件，除該工具 之外DOClever（開源）也是一個不錯的API管理工具，也支持Swagger文件導(dǎo)入（具體工具用法，大家可以去看他們的官網(wǎng)）

五、總結(jié)

Swagger是一個很好的工具，并且在前后端分離開發(fā)越來越流行的情況下，在后續(xù)的開發(fā)過程中，我覺得會扮演著越來越重要的作用，目前我們公司小的項目已經(jīng)準備開始使用swagger+yapi進行API的管理方式，而這篇文章也是這段時間抽空整理API管理的結(jié)果，希望可以幫助到大家，這里可能有很多不足的地方，歡迎大家拍磚，也希望可以跟大家一起進步

關(guān)于“.NET Core怎么利用swagger進行API接口文檔管理”這篇文章就分享到這里了，希望以上內(nèi)容可以對大家有一定的幫助，使各位可以學到更多知識，如果覺得文章不錯，請把它分享出去讓更多的人看到。

當前題目：.NETCore怎么利用swagger進行API接口文檔管理-創(chuàng)新互聯(lián)
分享網(wǎng)址：http://www.rwnh.cn/article32/esssc.html

成都網(wǎng)站建設(shè)公司_創(chuàng)新互聯(lián)，為您提供動態(tài)網(wǎng)站、微信小程序、網(wǎng)站內(nèi)鏈、小程序開發(fā)、網(wǎng)站排名、關(guān)鍵詞優(yōu)化

廣告

聲明：本網(wǎng)站發(fā)布的內(nèi)容（圖片、視頻和文字）以用戶投稿、用戶轉(zhuǎn)載內(nèi)容為主，如果涉及侵權(quán)請盡快告知，我們將會在第一時間刪除。文章觀點不代表本網(wǎng)站立場，如需處理請聯(lián)系客服。電話：028-86922220；郵箱：631063699@qq.com。內(nèi)容未經(jīng)允許不得轉(zhuǎn)載，或轉(zhuǎn)載時需注明來源： 創(chuàng)新互聯(lián)