當前位置：首頁 > 编程语言 > asp.net >内容正文

asp.net

.NET Core使用swagger进行API接口文档管理

發(fā)布時間：2023/12/4 asp.net 29 豆豆

生活随笔收集整理的這篇文章主要介紹了 .NET Core使用swagger进行API接口文档管理小編覺得挺不錯的,現(xiàn)在分享給大家,幫大家做個參考.

一、問題背景

　　隨著技術的發(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>

? ? ? ? /// 復雜數(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帶到服務中，例如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支持導入swagger生成的JSON文件，除該工具之外DOClever（開源）也是一個不錯的API管理工具，也支持Swagger文件導入（具體工具用法，大家可以去看他們的官網(wǎng)）

五、總結(jié)

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

原文地址:?https://www.cnblogs.com/OMango/p/8460092.html

.NET社區(qū)新聞，深度好文，歡迎訪問公眾號文章匯總 http://www.csharpkit.com

總結(jié)

以上是生活随笔為你收集整理的.NET Core使用swagger进行API接口文档管理的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。

上一篇： .NET Core 2.1路线图
下一篇： .NET下使用socket.io随笔记录