api在線(xiàn)文檔生成器（如何生成api文檔）

本篇文章給大家談?wù)刟pi在線(xiàn)文檔生成器，以及如何生成api文檔對(duì)應(yīng)的知識(shí)點(diǎn)，希望對(duì)各位有所幫助，不要忘了收藏本站喔。 今天給各位分享api在線(xiàn)文檔生成器的知識(shí)，其中也會(huì)對(duì)如何生成api文檔進(jìn)行解釋?zhuān)绻芘銮山鉀Q你現(xiàn)在面臨的問(wèn)題，別忘了關(guān)注本站，現(xiàn)在開(kāi)始吧！

本文目錄一覽：

• 1、還在發(fā)愁寫(xiě)API文檔？推薦一款阿里騰訊都在用的API管理神器
• 2、如何使 WebAPI 自動(dòng)生成漂亮又實(shí)用在線(xiàn)API文檔
• 3、好用高效的在線(xiàn)文檔編輯工具是哪個(gè)？

還在發(fā)愁寫(xiě)API文檔？推薦一款阿里騰訊都在用的API管理神器

作為一個(gè)前后端分離模式開(kāi)發(fā)api在線(xiàn)文檔生成器的團(tuán)隊(duì)，我們經(jīng)常會(huì)看到這樣的場(chǎng)景：前端開(kāi)發(fā)和后端開(kāi)發(fā)在一起熱烈的討論“api在線(xiàn)文檔生成器你這接口參數(shù)怎么又變api在線(xiàn)文檔生成器了？”，“接口怎么又不通了？”，“稍等，我調(diào)試下”，“你再試試..."。

那能不能寫(xiě)好接口文檔，大家都按文檔來(lái)開(kāi)發(fā)？很難，因?yàn)閷?xiě)文檔、維護(hù)文檔比較麻煩，而且費(fèi)時(shí)，還會(huì)經(jīng)常出現(xiàn) API 更新了，但文檔還是舊的，各種同步不一致的情況，從而耽擱彼此的時(shí)間。

之前我們團(tuán)隊(duì)也遇到了同樣的問(wèn)題，那么作為研發(fā)團(tuán)隊(duì)的負(fù)責(zé)人，我是如何帶領(lǐng)團(tuán)隊(duì)解決這個(gè)問(wèn)題的呢？

方法其實(shí)很簡(jiǎn)單，如果能做到讓寫(xiě)文檔/維護(hù)文檔這件事情的短期收益就能遠(yuǎn)高于付出的成本，那么所有問(wèn)題都能迎刃而解，開(kāi)發(fā)人員就會(huì)非常樂(lè)意去寫(xiě)接口文檔。

要做到寫(xiě)文檔和及時(shí)維護(hù)文檔的短期收益就能遠(yuǎn)高于付出的成本，無(wú)非兩個(gè)方向：

鑒于此，我們?cè)O(shè)想如果有一款工具做到以下這些是不是就非常爽了？

總結(jié)下來(lái)，我們需要的就是這么一款工具：

為此，我們幾乎嘗遍了市面上所有相關(guān)的工具，但是很遺憾，沒(méi)有找到合適的。

于是，我們自己實(shí)現(xiàn)了一個(gè)Postman + Swagger + RAP + JMeter

這個(gè)工具就是 Apifox，經(jīng)常很長(zhǎng)一段時(shí)間不斷更新迭代后，我們基本上完全實(shí)現(xiàn)了最初的設(shè)想，幾乎完美解決了最開(kāi)始遇到的所有問(wèn)題，在公司內(nèi)部大受歡迎。并且也形成了我們自己的最佳實(shí)踐。

沒(méi)錯(cuò)，現(xiàn)在我們已經(jīng)將Apifox產(chǎn)品化對(duì)外服務(wù)了，你們團(tuán)隊(duì)也可以直接使用Apifox了。

官網(wǎng)：www.apifox.cn

Apifox = Postman + Swagger + Mock + JMeter

Apifox 是 API 文檔、API 調(diào)試、API Mock、API 自動(dòng)化測(cè)試一體化協(xié)作平臺(tái)。

通過(guò)一套系統(tǒng)、一份數(shù)據(jù)，解決多個(gè)系統(tǒng)之間的數(shù)據(jù)同步問(wèn)題。只要定義好接口文檔，接口調(diào)試、數(shù)據(jù) Mock、接口測(cè)試就可以直接使用，無(wú)需再次定義api在線(xiàn)文檔生成器；接口文檔和接口開(kāi)發(fā)調(diào)試使用同一個(gè)工具，接口調(diào)試完成后即可保證和接口文檔定義完全一致。高效、及時(shí)、準(zhǔn)確！

節(jié)省研發(fā)團(tuán)隊(duì)的每一分鐘！

如果你認(rèn)為 Apifox 只做了數(shù)據(jù)打通，來(lái)提升研發(fā)團(tuán)隊(duì)的效率，那就錯(cuò)了。Apifox 還做了非常多的創(chuàng)新，來(lái)提升開(kāi)發(fā)人員的效率。

通常一個(gè)接口會(huì)有多種情況用例，比如 正確用例 參數(shù)錯(cuò)誤用例 數(shù)據(jù)為空用例 不同數(shù)據(jù)狀態(tài)用例。定義接口的時(shí)候定義好這些不同狀態(tài)的用例，接口調(diào)試的時(shí)候直接運(yùn)行，非常高效。

可以獨(dú)立定義數(shù)據(jù)模型，接口定義時(shí)可以直接引用數(shù)據(jù)模型，數(shù)據(jù)模型之間也可以相互引用。同樣的數(shù)據(jù)結(jié)構(gòu)，只需要定義一次即可多處使用；修改的時(shí)候只需要修改一處，多處實(shí)時(shí)更新，避免不一致。

使用 Apifox 調(diào)試接口的時(shí)候，系統(tǒng)會(huì)根據(jù)接口文檔里的定義，自動(dòng)校驗(yàn)返回的數(shù)據(jù)結(jié)構(gòu)是否正確，無(wú)需通過(guò)肉眼識(shí)別，也無(wú)需手動(dòng)寫(xiě)斷言腳本檢測(cè)，非常高效！

Apifox 自動(dòng)校驗(yàn)數(shù)據(jù)結(jié)構(gòu)

設(shè)置斷言：

Apifox 設(shè)置斷言

運(yùn)行后，查看斷言結(jié)果：

先放一張圖對(duì)比下 Apifox 和其他同類(lèi)工具 零配置 mock 出來(lái)的數(shù)據(jù)效果：

Apifox Mock 數(shù)據(jù)結(jié)果對(duì)比同類(lèi)工具

可以看出 Apifox 零配置 Mock 出來(lái)的數(shù)據(jù)和真實(shí)情況是非常接近的，前端開(kāi)發(fā)可以直接使用，而無(wú)需再手動(dòng)寫(xiě) mock 規(guī)則。

「Apifox 如何做到高效率、零配置生成非常人性化的 mock 數(shù)據(jù)」

Apifox 項(xiàng)目可“在線(xiàn)分享” API 文檔，分享出去的 API 文檔可設(shè)置為公開(kāi)或需要密碼訪(fǎng)問(wèn)，非常方便與外部團(tuán)隊(duì)協(xié)作。

體驗(yàn)地址：https://www.apipark.cn/s/ce387612-cfdb-478a-b604-b96d1dbc511b/http/5041285

根據(jù)接口模型定義，自動(dòng)生成各種語(yǔ)言/框架（如 TypeScript、Java、Go、Swift、ObjectiveC、Kotlin、Dart、C++、C#、Rust 等）的業(yè)務(wù)代碼（如 Model、Controller、單元測(cè)試代碼等）和接口請(qǐng)求代碼。目前 Apifox 支持 130 種語(yǔ)言及框架的代碼自動(dòng)生成。

更重要的是：你可以通過(guò)自定義代碼模板來(lái)生成符合自己團(tuán)隊(duì)的架構(gòu)規(guī)范的代碼，滿(mǎn)足各種個(gè)性化的需求。

接口調(diào)試

Apifox 多種主題色可選

如何使 WebAPI 自動(dòng)生成漂亮又實(shí)用在線(xiàn)API文檔

1.1 SwaggerUI
SwaggerUI 是一個(gè)簡(jiǎn)單的Restful API 測(cè)試和文檔工具。簡(jiǎn)單、漂亮、易用（官方demo）。通過(guò)讀取JSON 配置顯示API. 項(xiàng)目本身僅僅也只依賴(lài)一些 html,css.js靜態(tài)文件. 你可以幾乎放在任何Web容器上使用。
1.2 Swashbuckle
Swashbuckle 是.NET類(lèi)庫(kù),可以將WebAPI所有開(kāi)放的控制器方法生成對(duì)應(yīng)SwaggerUI的JSON配置。再通過(guò)SwaggerUI 顯示出來(lái)。類(lèi)庫(kù)中已經(jīng)包含SwaggerUI 。所以不需要額外安裝。
2.快速開(kāi)始
創(chuàng)建項(xiàng)目 OnlineAPI來(lái)封裝百度音樂(lè)服務(wù)(示例下載) ，通過(guò)API可以搜索、獲取音樂(lè)的信息和播放連接。
我盡量刪除一些我們demo中不會(huì)用到的一些文件，使其看上去比較簡(jiǎn)潔。
WebAPI 安裝 Swashbuckle
Install-Package Swashbuckle
代碼注釋生成文檔說(shuō)明。
Swashbuckle 是通過(guò)生成的XML文件來(lái)讀取注釋的，生成 SwaggerUI，JSON 配置中的說(shuō)明的。
安裝時(shí)會(huì)在項(xiàng)目目錄 App_Start 文件夾下生成一個(gè) SwaggerConfig.cs 配置文件，用于配置 SwaggerUI 相關(guān)展示行為的。如圖：
將配置文件大概99行注釋去掉并修改為
c.IncludeXmlComments(GetXmlCommentsPath(thisAssembly.GetName().Name));
并在當(dāng)前類(lèi)中添加一個(gè)方法
/// <summary
/// </summary
/// <param name="name"</param
/// <returns</returns
protected static string GetXmlCommentsPath(string name)
{
return string.Format(@"{0}\bin\{1}.XML", AppDomain.CurrentDomain.BaseDirectory, name);
}
緊接著你在此Web項(xiàng)目屬性生成選卡中勾選 “XML 文檔文件”，編譯過(guò)程中生成類(lèi)庫(kù)的注釋文件
添加百度音樂(lè) 3個(gè)API
訪(fǎng)問(wèn) lt;youhost/swagger/ui/index,最終顯示效果
我們通過(guò)API 測(cè)試API 是否成功運(yùn)行
3.添加自定義HTTP Header
在開(kāi)發(fā)移動(dòng)端 API時(shí)常常需要驗(yàn)證權(quán)限，驗(yàn)證參數(shù)放在Http請(qǐng)求頭中是再好不過(guò)了。WebAPI配合過(guò)濾器驗(yàn)證權(quán)限即可
首先我們需要?jiǎng)?chuàng)建一個(gè) IOperationFilter 接口的類(lèi)。IOperationFilter
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Http;
using System.Web.Http.Description;
using System.Web.Http.Filters;
using Swashbuckle.Swagger;
namespace OnlineAPI.Utility
{
public class HttpHeaderFilter : IOperationFilter
{
public void Apply(Operation operation, SchemaRegistry
schemaRegistry, ApiDescription apiDescription)
{
if (operation.parameters == null) operation.parameters = new
List<Parameter();
var filterPipeline =
apiDescription.ActionDescriptor.GetFilterPipeline();
//判斷是否添加權(quán)限過(guò)濾器
var isAuthorized = filterPipeline.Select(filterInfo =
filterInfo.Instance).Any(filter = filter is IAuthorizationFilter);
//判斷是否允許匿名方法
var allowAnonymous =
apiDescription.ActionDescriptor.GetCustomAttributes<AllowAnonymousAttribute().Any();
if (isAuthorized !allowAnonymous)
{
operation.parameters.Add(new Parameter
{
name = "access-key",
@in = "header",
description = "用戶(hù)訪(fǎng)問(wèn)Key",
required = false,
type = "string"
});
}
}
}
}
在 SwaggerConfig.cs 的 EnableSwagger 配置匿名方法類(lèi)添加一行注冊(cè)代碼
c.OperationFilter<HttpHeaderFilter();
添加Web權(quán)限過(guò)濾器
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Text;
using System.Web;
using System.Web.Http;
using System.Web.Http.Controllers;
using Newtonsoft.Json;
namespace OnlineAPI.Utility
{
/// <summary
///
/// </summary
public class AccessKeyAttribute : AuthorizeAttribute
{
/// <summary
/// 權(quán)限驗(yàn)證
/// </summary
/// <param name="actionContext"</param
/// <returns</returns
protected override bool IsAuthorized(HttpActionContext actionContext)
{
var request = actionContext.Request;
if (request.Headers.Contains("access-key"))
{
var accessKey = request.Headers.GetValues("access-key").SingleOrDefault();
//TODO 驗(yàn)證Key
return accessKey == "123456789";
}
return false;
}
/// <summary
/// 處理未授權(quán)的請(qǐng)求
/// </summary
/// <param name="actionContext"</param
protected override void HandleUnauthorizedRequest(HttpActionContext actionContext)
{
var content = JsonConvert.SerializeObject(new {State = HttpStatusCode.Unauthorized});
actionContext.Response = new HttpResponseMessage
{
Content = new StringContent(content, Encoding.UTF8, "application/json"),
StatusCode = HttpStatusCode.Unauthorized
};
}
}
}
在你想要的ApiController 或者是 Action 添加過(guò)濾器
[AccessKey]
最終顯示效果
4.顯示上傳文件參數(shù)
SwaggerUI 有上傳文件的功能和添加自定義HTTP Header 做法類(lèi)似，只是我們通過(guò)特殊的設(shè)置來(lái)標(biāo)示API具有上傳文件的功能
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Http.Description;
using Swashbuckle.Swagger;
namespace OnlineAPI.Utility
{
/// <summary
///
/// </summary
public class UploadFilter : IOperationFilter
{
/// <summary
/// 文件上傳
/// </summary
/// <param name="operation"</param
/// <param name="schemaRegistry"</param
/// <param name="apiDescription"</param
public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
{
if (!string.IsNullOrWhiteSpace(operation.summary) operation.summary.Contains("upload"))
{
operation.consumes.Add("application/form-data");
operation.parameters.Add(new Parameter
{
name = "file",
@in = "formData",
required = true,
type = "file"
});
}
}
}
}
在 SwaggerConfig.cs 的 EnableSwagger 配置匿名方法類(lèi)添加一行注冊(cè)代碼
c.OperationFilter<UploadFilter();
API 文檔展示效果

好用高效的在線(xiàn)文檔編輯工具是哪個(gè)？

好用高效的在線(xiàn)文檔編輯工具推薦Baklib。

文檔協(xié)作軟件我目前用過(guò)比較好的但是也比較小眾的就是baklib。

在我們了解軟件之前，讓我們談?wù)劄槭裁次覀冃枰臋n協(xié)作工具。

實(shí)時(shí)協(xié)作：如果多個(gè)團(tuán)隊(duì)成員經(jīng)常處理同一個(gè)可交付成果，文檔協(xié)作工具將為您省去很多麻煩。

版本控制：這些工具的真正優(yōu)點(diǎn)在于你擁有高級(jí)的“撤消”功能，大多數(shù)工具允許查看文檔的先前版本并在需要時(shí)恢復(fù)它們。

管理審核流程的能力：通過(guò)電子郵件共享反饋可能無(wú)效，因?yàn)橐话闶占渲杏泻芏嘣胍簟Ｎ臋n協(xié)作工具可讓你和你的同事專(zhuān)注于手頭的任務(wù)，消除所有其他干擾。

提高安全性：電子郵件可能被轉(zhuǎn)發(fā)或意外發(fā)送給錯(cuò)誤的人。文檔協(xié)作工具使你能夠控制誰(shuí)可以訪(fǎng)問(wèn)你的文件。

使用情況跟蹤和報(bào)告：這在許多情況下都很有用。想象一下，你正在培訓(xùn)一位新員工，并且你想知道他們是否看到了你的入職說(shuō)明，或者你想知道你的老板是否看到了你上周發(fā)送給她的報(bào)告。

集中式知識(shí)庫(kù)：一些文檔協(xié)作工具包括將文件組織到可搜索庫(kù)中的選項(xiàng)，這使得管理團(tuán)隊(duì)的集體知識(shí)變得更加容易。

最適合：在線(xiàn)制作知識(shí)庫(kù)、產(chǎn)品手冊(cè)、幫助中心、API文檔、產(chǎn)品介紹、在線(xiàn)手冊(cè)等，內(nèi)部知識(shí)協(xié)同和外部宣傳。

它是一個(gè)文檔協(xié)作工具，它還是一個(gè)成熟的知識(shí)庫(kù)，使您能夠與您的團(tuán)隊(duì)或客戶(hù)快速捕獲、存儲(chǔ)和共享信息。

在文檔協(xié)作方面，它提供了一個(gè)簡(jiǎn)潔明了的界面，讓你可以快速創(chuàng)建文檔并共同編輯它們，同時(shí)跟蹤以前的版本。多個(gè)訪(fǎng)問(wèn)級(jí)別讓你可以完全控制誰(shuí)可以看到你的內(nèi)容——你可以在線(xiàn)發(fā)布、在內(nèi)部共享、生成通用的可共享 URL 或邀請(qǐng)?zhí)囟ǖ娜恕?/p> 關(guān)于api在線(xiàn)文檔生成器和如何生成api文檔的介紹到此就結(jié)束了，不知道你從中找到你需要的信息了嗎 ？如果你還想了解更多這方面的信息，記得收藏關(guān)注本站。 api在線(xiàn)文檔生成器的介紹就聊到這里吧，感謝你花時(shí)間閱讀本站內(nèi)容，更多關(guān)于如何生成api文檔、api在線(xiàn)文檔生成器的信息別忘了在本站進(jìn)行查找喔。

版權(quán)聲明：本文內(nèi)容由網(wǎng)絡(luò)用戶(hù)投稿，版權(quán)歸原作者所有，本站不擁有其著作權(quán)，亦不承擔(dān)相應(yīng)法律責(zé)任。如果您發(fā)現(xiàn)本站中有涉嫌抄襲或描述失實(shí)的內(nèi)容，請(qǐng)聯(lián)系我們jiasou666@gmail.com 處理，核實(shí)后本網(wǎng)站將在24小時(shí)內(nèi)刪除侵權(quán)內(nèi)容。

版權(quán)聲明：本文內(nèi)容由網(wǎng)絡(luò)用戶(hù)投稿，版權(quán)歸原作者所有，本站不擁有其著作權(quán)，亦不承擔(dān)相應(yīng)法律責(zé)任。如果您發(fā)現(xiàn)本站中有涉嫌抄襲或描述失實(shí)的內(nèi)容，請(qǐng)聯(lián)系我們jiasou666@gmail.com 處理，核實(shí)后本網(wǎng)站將在24小時(shí)內(nèi)刪除侵權(quán)內(nèi)容。