亞寵展、全球?qū)櫸锂a(chǎn)業(yè)風向標——亞洲寵物展覽會深度解析
713
2025-04-01
在線api接口文檔系統(tǒng)（在線api接口文檔系統(tǒng)怎么用）
本篇文章給大家談談在線api接口文檔系統(tǒng)，以及在線api接口文檔系統(tǒng)怎么用對應的知識點，希望對各位有所幫助，不要忘了收藏本站喔。
今天給各位分享在線api接口文檔系統(tǒng)的知識，其中也會對在線api接口文檔系統(tǒng)怎么用進行解釋，如果能碰巧解決你現(xiàn)在面臨的問題，別忘了關注本站，現(xiàn)在開始吧！
API接口是什么？
為什么我們需要API接口？
API接口的核心
一、API接口是什么？
我們來以一個常見的數(shù)學公式理解API，比如y=x+2，當x=2的時候，y=4，對么？
那此時，我們把y=x+2稱為接口，x=2稱為參數(shù)，y=4稱為返回結(jié)果，那這個接口的功能就是能把我們輸入的數(shù)加上2（注意：這里你可以發(fā)現(xiàn)接口自身是帶有邏輯的）。
類比地，我們來理解一個常見的場景，比如現(xiàn)在有一個可以把經(jīng)緯度轉(zhuǎn)化為城市的接口，那當我輸入經(jīng)度是55°，緯度是88°的時候，接口通過自己的邏輯運算，返回結(jié)果告訴我：杭州市。
這樣你就可以清晰地了解百度百科的官方解釋了，接口就是預先定義的函數(shù)邏輯，他是供其他系統(tǒng)請求，然后返回結(jié)果的一個東西。
二、為什么我們需要API接口？
背景：我們的業(yè)務系統(tǒng)涉及多方多面，如果要一個公司或者一個系統(tǒng)把所有業(yè)務都做完，那未免工作量太大了吧？并且如果其他系統(tǒng)或公司有更好的運算邏輯，那我們在設計功能的時候可以考慮利用接口進行開發(fā)。
核心需求：利用現(xiàn)有接口可以降低開發(fā)成本，縮短開發(fā)成本。
舉個例子：比如我是打車的APP，現(xiàn)在我需要在我的頁面上展現(xiàn)地圖的功能，對于我司而言，新做地圖功能未免成本過高，那我們可以在高德開放平臺或者百度地圖的開放平臺，找到地圖API，這樣的話我們只需要購買高德的服務，部署調(diào)用高德地圖API，這樣就可以快速在我們頁面上線地圖功能了。
三、API接口的核心
對于小白而言，初看API文檔可能是一頭霧水的——從哪里看，怎么看，看什么是擺在面前的問題。
其實對于產(chǎn)品經(jīng)理而言，我們應該更關注這個公司可以提供什么樣的API接口服務，比如我知道高德可以提供地圖API，規(guī)劃路線的API，這樣的話在我們設計功能和工作中就可以想到調(diào)用他們的服務或者參考。
所以產(chǎn)品小白們看不懂也不用過于擔心，未來工作中你也會更深入了解清楚，因為看懂并不復雜，以下是API接口的核心點，所有的說明文檔離不開這5個核心點。
以下說明均以微信開放平臺為例說明，文末有各開放平臺的地址，大家有空可以去學習。好了，事不宜遲，現(xiàn)在我們來建立一個場景。
我們現(xiàn)在有一個APP，需要用戶在購買的時候調(diào)起微信支付的API，完成購買。請各位自動進入這個場景，把自己當作一位產(chǎn)品經(jīng)理。
1. 接口地址
現(xiàn)在Now，用戶點擊付款，我們需要告訴微信，我們要調(diào)起你們的收銀臺啦！但，去哪里告訴呢？這就需要接口地址了，也就相當于向微信的這條鏈接傳輸指定的數(shù)據(jù)。
一個鏈接地址不是我們理解的一個頁面，你可以理解是一個電話號碼，小白們要改變這個觀念。
此時我們可以看到接口文檔告訴我們鏈接是如下這條，那我們現(xiàn)在已經(jīng)撥通微信的電話了。
2. 請求參數(shù)（報文）
我們現(xiàn)在需要告訴微信，你想調(diào)用收銀臺對吧。那我們需要寫下來，此時生成的叫做報文，也就是你想告訴這個接口的內(nèi)容是什么？相當于前文函數(shù)的輸入x=2。
一般來說，報文的格式和內(nèi)容都是按接口文檔規(guī)定的。如下文就是微信開放平臺對調(diào)起收銀臺的報文要求。
我們先來看前2個參數(shù)，你現(xiàn)在跟微信在對話，是不是應該先告訴微信，你是誰？這里微信的文檔告訴你應該要用應用ID+商戶號來確定你的身份，什么意思呢？
比如你是A商戶，下面有a，b，c三個APP，所以微信要知道你是哪個商家，下面的哪個APP要用收銀臺。這是非常重要的，微信后面要把收到的錢打到對應的賬戶以及統(tǒng)計數(shù)據(jù)等。
那我們就在報文里面寫下這兩句話：
<appidwx2421b1c4370ec43b</appid（我的應用ID是wx2421…….）
<mch_id10000100</mch_id（我的商戶號是10000…….）
好了，現(xiàn)在微信知道你是誰了，那你要告訴微信，你需要微信支付幫你收多少錢對吧？這里定義了貨幣類型和總金額，也就是收什么貨幣，收多少錢。
這里你看，貨幣類型的必填寫了否，也就是說你也可以不告訴微信支付貨幣類型是什么，因為他在后面?zhèn)渥⒘四J是人民幣。
好的，那我們寫下兩段報文
<free_typeCNY</ free_type （我要收人民幣）
<total_fee1</total_fee（我要收1元）
好了，現(xiàn)在微信知道你是誰，也知道要收多少錢了，那接下來微信支付要把收錢結(jié)果告訴你呀，因為你得知道用戶是成功支付了才能繼續(xù)發(fā)貨，服務啊等等的。所以這里我們用到通知地址，就是告訴微信，等下完事了他去哪里告訴你支付結(jié)果。那我們把地址寫好：
<notify_urlhttp://wxpay.wxutil.com/pub_v2/pay/notify.v2.php</notify_url
3. 返回結(jié)果
剛剛微信支付已經(jīng)去收款了，現(xiàn)在他要在我們留下的通知地址中，告訴我們結(jié)果了。結(jié)果無非是兩種：成功收款？收款不成功？
（1）成功
很順利，現(xiàn)在用戶成功付錢了，并且微信也把成功的消息告訴我們了，并且他還把用戶支付的一些信息也告訴我們。
那這里就是微信支付成功收款后告訴我們的信息。
應用APPID，商戶號：告訴你我成功扣款的是哪家商戶的哪個APPID的交易。
業(yè)務結(jié)果：成功或失敗
（2）失敗
在產(chǎn)品設計的時候，我們往往很關注失敗的情況，當收款失敗的時候，微信同時會告訴你失敗的原因，如下圖很好理解，失敗的原因有很多很多種，我們在設計的時候往往要分析每種失敗的原因，為每個失敗的原因設計頁面和用戶提示，以確保用戶能理解。
以上就是API接口基本運作模式的理解，下面我將繼續(xù)更新API接口的一些更為深入和細節(jié)的關鍵元素，如請求方式/簽名/加解密等等。
可供參考的開放平臺網(wǎng)站
微信支付：https://pay.weixin.qq.com/wiki/doc/api/index.html
高德平臺開放平臺：https://lbs.amap.com/
其中不可避免的就是定制好接口文檔，后端工程師要寫好單元測試，推薦使用 chrome 的插件 postman 或 soapui或 jmeter，service 層的測試用例拿 junit 寫。
但是這種情況對于接口文檔管理很不方便，所以下面就羅列一些互聯(lián)網(wǎng)公司常用的接口文檔管理平臺。
Swagger是一個大型的API開發(fā)者的工具框架，該框架提出了一個編寫OpenAPI的規(guī)范（命名為OAS），并且Swagger可以跨整個API生命周期進行開發(fā)，從設計和文檔到測試和部署。
Swagger框架三核心：
YApi部署流程介紹
YApi 是高效、易用、功能強大的 api 管理平臺，旨在為開發(fā)、產(chǎn)品、測試人員提供更優(yōu)雅的接口管理服務。它可以幫助開發(fā)者輕松創(chuàng)建、發(fā)布、以及維護API。除此之外，YApi 還為用戶提供了優(yōu)秀的交互體驗，開發(fā)人員只需利用平臺提供的接口數(shù)據(jù)寫入工具以及簡單的點擊操作就可以實現(xiàn)接口的管理。特性:
難點：如果需要要執(zhí)行自動化測試，需要編寫腳本。
Eolinker是國內(nèi)企業(yè)級IT研發(fā)管理解決方案服務品牌，在線API接口管理服務供應商，致力于滿足各行業(yè)客戶在不同應用環(huán)境中對研發(fā)管理全生命周期的個性化需求，提供API開發(fā)管理（AMS）、開發(fā)團隊協(xié)作、自動化測試、網(wǎng)關（AGW）以及監(jiān)控（AMT）等服務。
特性：
ShowDoc一個非常適合IT團隊的在線API文檔、技術文檔工具。
隨著移動互聯(lián)網(wǎng)的發(fā)展，BaaS（后端即服務）越來越流行。服務端提供API，APP端或者網(wǎng)頁前端便可方便調(diào)用數(shù)據(jù)。用ShowDoc可以非常方便快速地編寫出美觀的API文檔。
項目地址： https://www.showdoc.cc
DOClever是一個可視化接口管理工具 ,可以分析接口結(jié)構，校驗接口正確性， 圍繞接口定義文檔，通過一系列自動化工具提升我們的協(xié)作效率。
特性：
DOClever官網(wǎng)： http://www.doclever.cn/controller/index/index.html
DOClever GitHub： https://github.com/sx1989827/DOClever
阿里媽媽前端團隊出品的開源接口管理工具RAP第二代，RAP通過GUI工具幫助WEB工程師更高效的管理接口文檔，同時通過分析接口結(jié)構自動生成Mock數(shù)據(jù)、校驗真實接口的正確性，使接口文檔成為開發(fā)流程中的強依賴。有了結(jié)構化的API數(shù)據(jù)，RAP可以做的更多，而我們可以避免更多重復勞動。基于RAML的接口定義、文檔生成、Mock Server完成了定義和使用的分離，通過一套規(guī)范完成的接口定義，可以用不同的工具得到適應不同API管理系統(tǒng)的輸出，有更多的可能性，同時保持了核心定義不變。RAP較之于RAML，前者更加集中，所有的定義、文檔、mock都在同一個服務中完成，并且實時生效，方便快捷，如果只考慮方便易用，RAP是更好的選擇，而RAML顯得更加繁瑣，更適合于公開的接口定義，方便在各個系統(tǒng)之間流轉(zhuǎn)。
github源碼地址： https://github.com/thx/rap2-delos
SwaggerUI 是一個簡單的Restful API 測試和文檔工具。簡單、漂亮、易用（官方demo）。通過讀取JSON 配置顯示API. 項目本身僅僅也只依賴一些 html,css.js靜態(tài)文件. 你可以幾乎放在任何Web容器上使用。
1.2 Swashbuckle
Swashbuckle 是.NET類庫,可以將WebAPI所有開放的控制器方法生成對應SwaggerUI的JSON配置。再通過SwaggerUI 顯示出來。類庫中已經(jīng)包含SwaggerUI 。所以不需要額外安裝。
2.快速開始
創(chuàng)建項目 OnlineAPI來封裝百度音樂服務(示例下載) ，通過API可以搜索、獲取音樂的信息和播放連接。
我盡量刪除一些我們demo中不會用到的一些文件，使其看上去比較簡潔。
WebAPI 安裝 Swashbuckle
Install-Package Swashbuckle
代碼注釋生成文檔說明。
Swashbuckle 是通過生成的XML文件來讀取注釋的，生成 SwaggerUI，JSON 配置中的說明的。
安裝時會在項目目錄 App_Start 文件夾下生成一個 SwaggerConfig.cs 配置文件，用于配置 SwaggerUI 相關展示行為的。如圖：
將配置文件大概99行注釋去掉并修改為
c.IncludeXmlComments(GetXmlCommentsPath(thisAssembly.GetName().Name));
并在當前類中添加一個方法
/// <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項目屬性生成選卡中勾選 “XML 文檔文件”，編譯過程中生成類庫的注釋文件
添加百度音樂 3個API
訪問 lt;youhost/swagger/ui/index,最終顯示效果
我們通過API 測試API 是否成功運行
3.添加自定義HTTP Header
在開發(fā)移動端 API時常常需要驗證權限，驗證參數(shù)放在Http請求頭中是再好不過了。WebAPI配合過濾器驗證權限即可
首先我們需要創(chuàng)建一個 IOperationFilter 接口的類。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();
//判斷是否添加權限過濾器
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 = "用戶訪問Key",
required = false,
type = "string"
});
}
}
}
}
在 SwaggerConfig.cs 的 EnableSwagger 配置匿名方法類添加一行注冊代碼
c.OperationFilter<HttpHeaderFilter();
添加Web權限過濾器
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
/// 權限驗證
/// </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 驗證Key
return accessKey == "123456789";
}
return false;
}
/// <summary
/// 處理未授權的請求
/// </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 添加過濾器
[AccessKey]
最終顯示效果
4.顯示上傳文件參數(shù)
SwaggerUI 有上傳文件的功能和添加自定義HTTP Header 做法類似，只是我們通過特殊的設置來標示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 配置匿名方法類添加一行注冊代碼
c.OperationFilter<UploadFilter();
API 文檔展示效果
接口函數(shù)一旦發(fā)布就不能改了在線api接口文檔系統(tǒng)，要保持兼容性，拼寫錯誤也不能改了，所以要仔細檢查拼寫，否則會被同行嘲笑很多年。
著名悲劇在線api接口文檔系統(tǒng)：unix 在線api接口文檔系統(tǒng)的 creat
2. 不僅是英文單詞不要拼錯，時態(tài)也不要錯。
比如在線api接口文檔系統(tǒng)：
返回bool在線api接口文檔系統(tǒng)的判斷函數(shù)，單數(shù)要用 is 復數(shù)要用are，這樣你的命名就和文檔中的描述保持了一致性。
表示狀態(tài)的變量或者函數(shù)要注意時態(tài)，比如 onXxxxChanged 表示xxx已經(jīng)變化了，isConnecting表示正在連接。
正確的時態(tài)可以給使用者傳遞更豐富的信息。
3. 函數(shù)最好是動賓結(jié)構
動賓結(jié)構就是 doSomething，這樣的函數(shù)命名含義明確
比如： openFile, allocBuffer, setName
如果這個函數(shù)的動詞賓語就是這個對象本身，那么可以省略掉賓語
4. 屬性命名最好是定語+名詞
比如 fileName, maxSize, textColor
5. 不要用生僻單詞，這不是秀英語的地方，也不要用漢語拼音
比如：rendezvous，估計大多數(shù)人要去查詞典才知道什么意思，這個詞源自法語，是約會的意思。
Symbian OS里有個用它命名的函數(shù)，開發(fā)Symbian的是英國人，也許人家覺得很平常吧，反正我是查了詞典才知道的。
6. 不要自己發(fā)明縮寫
除非是約定俗成已經(jīng)被廣泛使用的縮寫，否則老老實實用完整拼寫。
壞例子: count-cnt, manager-mngr password-pw button-btn
現(xiàn)代的IDE都有很好的自動完成功能，名字長一點沒關系的，可讀性更重要。
7. 保持方法的對稱性，有些方法一旦出現(xiàn)就應該是成對的，
比如 有open就要有close，有alloc就要有free，有add就要有remove，這些單詞基本是固定搭配的，使用者就很容易理解。
如果 open對應clear就有點讓人困惑了。
本文目錄一覽：
- 1、還在發(fā)愁寫API文檔？推薦一款阿里騰訊都在用的API管理神器
- 2、API接口入門（一）：讀懂API接口文檔
- 3、六大接口管理平臺，總有一款適合你的！
- 4、如何使 WebAPI 自動生成漂亮又實用在線API文檔
- 5、如何優(yōu)雅的“編寫”api接口文檔
- 6、請教在線文檔的api
還在發(fā)愁寫API文檔？推薦一款阿里騰訊都在用的API管理神器
作為一個前后端分離模式開發(fā)的團隊，我們經(jīng)常會看到這樣的場景：前端開發(fā)和后端開發(fā)在一起熱烈的討論“你這接口參數(shù)怎么又變了？”，“接口怎么又不通了？”，“稍等，我調(diào)試下”，“你再試試..."。
那能不能寫好接口文檔，大家都按文檔來開發(fā)？很難，因為寫文檔、維護文檔比較麻煩，而且費時，還會經(jīng)常出現(xiàn) API 更新了，但文檔還是舊的，各種同步不一致的情況，從而耽擱彼此的時間。
之前我們團隊也遇到了同樣的問題，那么作為研發(fā)團隊的負責人，我是如何帶領團隊解決這個問題的呢？
方法其實很簡單，如果能做到讓寫文檔/維護文檔這件事情的短期收益就能遠高于付出的成本，那么所有問題都能迎刃而解，開發(fā)人員就會非常樂意去寫接口文檔。
要做到寫文檔和及時維護文檔的短期收益就能遠高于付出的成本，無非兩個方向：
鑒于此，我們設想如果有一款工具做到以下這些是不是就非常爽了？
總結(jié)下來，我們需要的就是這么一款工具：
為此，我們幾乎嘗遍了市面上所有相關的工具，但是很遺憾，沒有找到合適的。
于是，我們自己實現(xiàn)了一個Postman + Swagger + RAP + JMeter
這個工具就是 Apifox，經(jīng)常很長一段時間不斷更新迭代后，我們基本上完全實現(xiàn)了最初的設想，幾乎完美解決了最開始遇到的所有問題，在公司內(nèi)部大受歡迎。并且也形成了我們自己的最佳實踐。
沒錯，現(xiàn)在我們已經(jīng)將Apifox產(chǎn)品化對外服務了，你們團隊也可以直接使用Apifox了。
官網(wǎng)：www.apifox.cn
Apifox = Postman + Swagger + Mock + JMeter
Apifox 是 API 文檔、API 調(diào)試、API Mock、API 自動化測試一體化協(xié)作平臺。
通過一套系統(tǒng)、一份數(shù)據(jù)，解決多個系統(tǒng)之間的數(shù)據(jù)同步問題。只要定義好接口文檔，接口調(diào)試、數(shù)據(jù) Mock、接口測試就可以直接使用，無需再次定義；接口文檔和接口開發(fā)調(diào)試使用同一個工具，接口調(diào)試完成后即可保證和接口文檔定義完全一致。高效、及時、準確！
節(jié)省研發(fā)團隊的每一分鐘！
如果你認為 Apifox 只做了數(shù)據(jù)打通，來提升研發(fā)團隊的效率，那就錯了。Apifox 還做了非常多的創(chuàng)新，來提升開發(fā)人員的效率。
通常一個接口會有多種情況用例，比如 正確用例 參數(shù)錯誤用例 數(shù)據(jù)為空用例 不同數(shù)據(jù)狀態(tài)用例。定義接口的時候定義好這些不同狀態(tài)的用例，接口調(diào)試的時候直接運行，非常高效。
可以獨立定義數(shù)據(jù)模型，接口定義時可以直接引用數(shù)據(jù)模型，數(shù)據(jù)模型之間也可以相互引用。同樣的數(shù)據(jù)結(jié)構，只需要定義一次即可多處使用；修改的時候只需要修改一處，多處實時更新，避免不一致。
使用 Apifox 調(diào)試接口的時候，系統(tǒng)會根據(jù)接口文檔里的定義，自動校驗返回的數(shù)據(jù)結(jié)構是否正確，無需通過肉眼識別，也無需手動寫斷言腳本檢測，非常高效！
Apifox 自動校驗數(shù)據(jù)結(jié)構
設置斷言：
Apifox 設置斷言
運行后，查看斷言結(jié)果：
先放一張圖對比下 Apifox 和其他同類工具 零配置 mock 出來的數(shù)據(jù)效果：
Apifox Mock 數(shù)據(jù)結(jié)果對比同類工具
可以看出 Apifox 零配置 Mock 出來的數(shù)據(jù)和真實情況是非常接近的，前端開發(fā)可以直接使用，而無需再手動寫 mock 規(guī)則。
「Apifox 如何做到高效率、零配置生成非常人性化的 mock 數(shù)據(jù)」
Apifox 項目可“在線分享” API 文檔，分享出去的 API 文檔可設置為公開或需要密碼訪問，非常方便與外部團隊協(xié)作。
體驗地址：https://www.apipark.cn/s/ce387612-cfdb-478a-b604-b96d1dbc511b/http/5041285
根據(jù)接口模型定義，自動生成各種語言/框架（如 TypeScript、Java、Go、Swift、ObjectiveC、Kotlin、Dart、C++、C#、Rust 等）的業(yè)務代碼（如 Model、Controller、單元測試代碼等）和接口請求代碼。目前 Apifox 支持 130 種語言及框架的代碼自動生成。
更重要的是：你可以通過自定義代碼模板來生成符合自己團隊的架構規(guī)范的代碼，滿足各種個性化的需求。
接口調(diào)試
Apifox 多種主題色可選
API接口入門（一）：讀懂API接口文檔
本文目錄：API接口是什么？
為什么我們需要API接口？
API接口的核心
一、API接口是什么？
我們來以一個常見的數(shù)學公式理解API，比如y=x+2，當x=2的時候，y=4，對么？
那此時，我們把y=x+2稱為接口，x=2稱為參數(shù)，y=4稱為返回結(jié)果，那這個接口的功能就是能把我們輸入的數(shù)加上2（注意：這里你可以發(fā)現(xiàn)接口自身是帶有邏輯的）。
類比地，我們來理解一個常見的場景，比如現(xiàn)在有一個可以把經(jīng)緯度轉(zhuǎn)化為城市的接口，那當我輸入經(jīng)度是55°，緯度是88°的時候，接口通過自己的邏輯運算，返回結(jié)果告訴我：杭州市。
這樣你就可以清晰地了解百度百科的官方解釋了，接口就是預先定義的函數(shù)邏輯，他是供其他系統(tǒng)請求，然后返回結(jié)果的一個東西。
二、為什么我們需要API接口？
背景：我們的業(yè)務系統(tǒng)涉及多方多面，如果要一個公司或者一個系統(tǒng)把所有業(yè)務都做完，那未免工作量太大了吧？并且如果其他系統(tǒng)或公司有更好的運算邏輯，那我們在設計功能的時候可以考慮利用接口進行開發(fā)。
核心需求：利用現(xiàn)有接口可以降低開發(fā)成本，縮短開發(fā)成本。
舉個例子：比如我是打車的APP，現(xiàn)在我需要在我的頁面上展現(xiàn)地圖的功能，對于我司而言，新做地圖功能未免成本過高，那我們可以在高德開放平臺或者百度地圖的開放平臺，找到地圖API，這樣的話我們只需要購買高德的服務，部署調(diào)用高德地圖API，這樣就可以快速在我們頁面上線地圖功能了。
三、API接口的核心
對于小白而言，初看API文檔可能是一頭霧水的——從哪里看，怎么看，看什么是擺在面前的問題。
其實對于產(chǎn)品經(jīng)理而言，我們應該更關注這個公司可以提供什么樣的API接口服務，比如我知道高德可以提供地圖API，規(guī)劃路線的API，這樣的話在我們設計功能和工作中就可以想到調(diào)用他們的服務或者參考。
所以產(chǎn)品小白們看不懂也不用過于擔心，未來工作中你也會更深入了解清楚，因為看懂并不復雜，以下是API接口的核心點，所有的說明文檔離不開這5個核心點。
以下說明均以微信開放平臺為例說明，文末有各開放平臺的地址，大家有空可以去學習。好了，事不宜遲，現(xiàn)在我們來建立一個場景。
我們現(xiàn)在有一個APP，需要用戶在購買的時候調(diào)起微信支付的API，完成購買。請各位自動進入這個場景，把自己當作一位產(chǎn)品經(jīng)理。
1. 接口地址
現(xiàn)在Now，用戶點擊付款，我們需要告訴微信，我們要調(diào)起你們的收銀臺啦！但，去哪里告訴呢？這就需要接口地址了，也就相當于向微信的這條鏈接傳輸指定的數(shù)據(jù)。
一個鏈接地址不是我們理解的一個頁面，你可以理解是一個電話號碼，小白們要改變這個觀念。
此時我們可以看到接口文檔告訴我們鏈接是如下這條，那我們現(xiàn)在已經(jīng)撥通微信的電話了。
2. 請求參數(shù)（報文）
我們現(xiàn)在需要告訴微信，你想調(diào)用收銀臺對吧。那我們需要寫下來，此時生成的叫做報文，也就是你想告訴這個接口的內(nèi)容是什么？相當于前文函數(shù)的輸入x=2。
一般來說，報文的格式和內(nèi)容都是按接口文檔規(guī)定的。如下文就是微信開放平臺對調(diào)起收銀臺的報文要求。
我們先來看前2個參數(shù)，你現(xiàn)在跟微信在對話，是不是應該先告訴微信，你是誰？這里微信的文檔告訴你應該要用應用ID+商戶號來確定你的身份，什么意思呢？
比如你是A商戶，下面有a，b，c三個APP，所以微信要知道你是哪個商家，下面的哪個APP要用收銀臺。這是非常重要的，微信后面要把收到的錢打到對應的賬戶以及統(tǒng)計數(shù)據(jù)等。
那我們就在報文里面寫下這兩句話：
<appidwx2421b1c4370ec43b</appid（我的應用ID是wx2421…….）
<mch_id10000100</mch_id（我的商戶號是10000…….）
好了，現(xiàn)在微信知道你是誰了，那你要告訴微信，你需要微信支付幫你收多少錢對吧？這里定義了貨幣類型和總金額，也就是收什么貨幣，收多少錢。
這里你看，貨幣類型的必填寫了否，也就是說你也可以不告訴微信支付貨幣類型是什么，因為他在后面?zhèn)渥⒘四J是人民幣。
好的，那我們寫下兩段報文
<free_typeCNY</ free_type （我要收人民幣）
<total_fee1</total_fee（我要收1元）
好了，現(xiàn)在微信知道你是誰，也知道要收多少錢了，那接下來微信支付要把收錢結(jié)果告訴你呀，因為你得知道用戶是成功支付了才能繼續(xù)發(fā)貨，服務啊等等的。所以這里我們用到通知地址，就是告訴微信，等下完事了他去哪里告訴你支付結(jié)果。那我們把地址寫好：
<notify_urlhttp://wxpay.wxutil.com/pub_v2/pay/notify.v2.php</notify_url
3. 返回結(jié)果
剛剛微信支付已經(jīng)去收款了，現(xiàn)在他要在我們留下的通知地址中，告訴我們結(jié)果了。結(jié)果無非是兩種：成功收款？收款不成功？
（1）成功
很順利，現(xiàn)在用戶成功付錢了，并且微信也把成功的消息告訴我們了，并且他還把用戶支付的一些信息也告訴我們。
那這里就是微信支付成功收款后告訴我們的信息。
應用APPID，商戶號：告訴你我成功扣款的是哪家商戶的哪個APPID的交易。
業(yè)務結(jié)果：成功或失敗
（2）失敗
在產(chǎn)品設計的時候，我們往往很關注失敗的情況，當收款失敗的時候，微信同時會告訴你失敗的原因，如下圖很好理解，失敗的原因有很多很多種，我們在設計的時候往往要分析每種失敗的原因，為每個失敗的原因設計頁面和用戶提示，以確保用戶能理解。
以上就是API接口基本運作模式的理解，下面我將繼續(xù)更新API接口的一些更為深入和細節(jié)的關鍵元素，如請求方式/簽名/加解密等等。
可供參考的開放平臺網(wǎng)站
微信支付：https://pay.weixin.qq.com/wiki/doc/api/index.html
高德平臺開放平臺：https://lbs.amap.com/
六大接口管理平臺，總有一款適合你的！
先聊一聊前端和后端分離的優(yōu)點。前后端分離優(yōu)點如下：其中不可避免的就是定制好接口文檔，后端工程師要寫好單元測試，推薦使用 chrome 的插件 postman 或 soapui或 jmeter，service 層的測試用例拿 junit 寫。
但是這種情況對于接口文檔管理很不方便，所以下面就羅列一些互聯(lián)網(wǎng)公司常用的接口文檔管理平臺。
Swagger是一個大型的API開發(fā)者的工具框架，該框架提出了一個編寫OpenAPI的規(guī)范（命名為OAS），并且Swagger可以跨整個API生命周期進行開發(fā)，從設計和文檔到測試和部署。
Swagger框架三核心：
YApi部署流程介紹
YApi 是高效、易用、功能強大的 api 管理平臺，旨在為開發(fā)、產(chǎn)品、測試人員提供更優(yōu)雅的接口管理服務。它可以幫助開發(fā)者輕松創(chuàng)建、發(fā)布、以及維護API。除此之外，YApi 還為用戶提供了優(yōu)秀的交互體驗，開發(fā)人員只需利用平臺提供的接口數(shù)據(jù)寫入工具以及簡單的點擊操作就可以實現(xiàn)接口的管理。特性:
難點：如果需要要執(zhí)行自動化測試，需要編寫腳本。
Eolinker是國內(nèi)企業(yè)級IT研發(fā)管理解決方案服務品牌，在線API接口管理服務供應商，致力于滿足各行業(yè)客戶在不同應用環(huán)境中對研發(fā)管理全生命周期的個性化需求，提供API開發(fā)管理（AMS）、開發(fā)團隊協(xié)作、自動化測試、網(wǎng)關（AGW）以及監(jiān)控（AMT）等服務。
特性：
ShowDoc一個非常適合IT團隊的在線API文檔、技術文檔工具。
隨著移動互聯(lián)網(wǎng)的發(fā)展，BaaS（后端即服務）越來越流行。服務端提供API，APP端或者網(wǎng)頁前端便可方便調(diào)用數(shù)據(jù)。用ShowDoc可以非常方便快速地編寫出美觀的API文檔。
項目地址： https://www.showdoc.cc
DOClever是一個可視化接口管理工具 ,可以分析接口結(jié)構，校驗接口正確性， 圍繞接口定義文檔，通過一系列自動化工具提升我們的協(xié)作效率。
特性：
DOClever官網(wǎng)： http://www.doclever.cn/controller/index/index.html
DOClever GitHub： https://github.com/sx1989827/DOClever
阿里媽媽前端團隊出品的開源接口管理工具RAP第二代，RAP通過GUI工具幫助WEB工程師更高效的管理接口文檔，同時通過分析接口結(jié)構自動生成Mock數(shù)據(jù)、校驗真實接口的正確性，使接口文檔成為開發(fā)流程中的強依賴。有了結(jié)構化的API數(shù)據(jù)，RAP可以做的更多，而我們可以避免更多重復勞動。基于RAML的接口定義、文檔生成、Mock Server完成了定義和使用的分離，通過一套規(guī)范完成的接口定義，可以用不同的工具得到適應不同API管理系統(tǒng)的輸出，有更多的可能性，同時保持了核心定義不變。RAP較之于RAML，前者更加集中，所有的定義、文檔、mock都在同一個服務中完成，并且實時生效，方便快捷，如果只考慮方便易用，RAP是更好的選擇，而RAML顯得更加繁瑣，更適合于公開的接口定義，方便在各個系統(tǒng)之間流轉(zhuǎn)。
github源碼地址： https://github.com/thx/rap2-delos
如何使 WebAPI 自動生成漂亮又實用在線API文檔
1.1 SwaggerUISwaggerUI 是一個簡單的Restful API 測試和文檔工具。簡單、漂亮、易用（官方demo）。通過讀取JSON 配置顯示API. 項目本身僅僅也只依賴一些 html,css.js靜態(tài)文件. 你可以幾乎放在任何Web容器上使用。
1.2 Swashbuckle
Swashbuckle 是.NET類庫,可以將WebAPI所有開放的控制器方法生成對應SwaggerUI的JSON配置。再通過SwaggerUI 顯示出來。類庫中已經(jīng)包含SwaggerUI 。所以不需要額外安裝。
2.快速開始
創(chuàng)建項目 OnlineAPI來封裝百度音樂服務(示例下載) ，通過API可以搜索、獲取音樂的信息和播放連接。
我盡量刪除一些我們demo中不會用到的一些文件，使其看上去比較簡潔。
WebAPI 安裝 Swashbuckle
Install-Package Swashbuckle
代碼注釋生成文檔說明。
Swashbuckle 是通過生成的XML文件來讀取注釋的，生成 SwaggerUI，JSON 配置中的說明的。
安裝時會在項目目錄 App_Start 文件夾下生成一個 SwaggerConfig.cs 配置文件，用于配置 SwaggerUI 相關展示行為的。如圖：
將配置文件大概99行注釋去掉并修改為
c.IncludeXmlComments(GetXmlCommentsPath(thisAssembly.GetName().Name));
并在當前類中添加一個方法
/// <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項目屬性生成選卡中勾選 “XML 文檔文件”，編譯過程中生成類庫的注釋文件
添加百度音樂 3個API
訪問 lt;youhost/swagger/ui/index,最終顯示效果
我們通過API 測試API 是否成功運行
3.添加自定義HTTP Header
在開發(fā)移動端 API時常常需要驗證權限，驗證參數(shù)放在Http請求頭中是再好不過了。WebAPI配合過濾器驗證權限即可
首先我們需要創(chuàng)建一個 IOperationFilter 接口的類。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();
//判斷是否添加權限過濾器
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 = "用戶訪問Key",
required = false,
type = "string"
});
}
}
}
}
在 SwaggerConfig.cs 的 EnableSwagger 配置匿名方法類添加一行注冊代碼
c.OperationFilter<HttpHeaderFilter();
添加Web權限過濾器
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
/// 權限驗證
/// </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 驗證Key
return accessKey == "123456789";
}
return false;
}
/// <summary
/// 處理未授權的請求
/// </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 添加過濾器
[AccessKey]
最終顯示效果
4.顯示上傳文件參數(shù)
SwaggerUI 有上傳文件的功能和添加自定義HTTP Header 做法類似，只是我們通過特殊的設置來標示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 配置匿名方法類添加一行注冊代碼
c.OperationFilter<UploadFilter();
API 文檔展示效果
如何優(yōu)雅的“編寫”api接口文檔
1. 拼寫要準確接口函數(shù)一旦發(fā)布就不能改了在線api接口文檔系統(tǒng)，要保持兼容性，拼寫錯誤也不能改了，所以要仔細檢查拼寫，否則會被同行嘲笑很多年。
著名悲劇在線api接口文檔系統(tǒng)：unix 在線api接口文檔系統(tǒng)的 creat
2. 不僅是英文單詞不要拼錯，時態(tài)也不要錯。
比如在線api接口文檔系統(tǒng)：
返回bool在線api接口文檔系統(tǒng)的判斷函數(shù)，單數(shù)要用 is 復數(shù)要用are，這樣你的命名就和文檔中的描述保持了一致性。
表示狀態(tài)的變量或者函數(shù)要注意時態(tài)，比如 onXxxxChanged 表示xxx已經(jīng)變化了，isConnecting表示正在連接。
正確的時態(tài)可以給使用者傳遞更豐富的信息。
3. 函數(shù)最好是動賓結(jié)構
動賓結(jié)構就是 doSomething，這樣的函數(shù)命名含義明確
比如： openFile, allocBuffer, setName
如果這個函數(shù)的動詞賓語就是這個對象本身，那么可以省略掉賓語
4. 屬性命名最好是定語+名詞
比如 fileName, maxSize, textColor
5. 不要用生僻單詞，這不是秀英語的地方，也不要用漢語拼音
比如：rendezvous，估計大多數(shù)人要去查詞典才知道什么意思，這個詞源自法語，是約會的意思。
Symbian OS里有個用它命名的函數(shù)，開發(fā)Symbian的是英國人，也許人家覺得很平常吧，反正我是查了詞典才知道的。
6. 不要自己發(fā)明縮寫
除非是約定俗成已經(jīng)被廣泛使用的縮寫，否則老老實實用完整拼寫。
壞例子: count-cnt, manager-mngr password-pw button-btn
現(xiàn)代的IDE都有很好的自動完成功能，名字長一點沒關系的，可讀性更重要。
7. 保持方法的對稱性，有些方法一旦出現(xiàn)就應該是成對的，
比如 有open就要有close，有alloc就要有free，有add就要有remove，這些單詞基本是固定搭配的，使用者就很容易理解。
如果 open對應clear就有點讓人困惑了。
請教在線文檔的api
Android中文版
api手冊地址：http://www.matools.com/api/android
Ant最新版
api手冊地址：http://www.matools.com/api/ant
ASM字節(jié)碼操作
api手冊地址：http://www.matools.com/api/asm
Axis2最新版
api手冊地址：http://www.matools.com/api/axis2
Bash腳本
api手冊地址：http://www.matools.com/api/bash
Bootstrap 3
api手冊地址：http://www.matools.com/api/bootstrap3
Bootstrap 4
api手冊地址：http://www.matools.com/api/bootstrap4
C/C++
api手冊地址：http://www.matools.com/api/c
C3P0連接池
api手冊地址：http://www.matools.com/api/c3p0
CentOS使用文檔
api手冊地址：http://www.matools.com/api/centos
Commons-Beanutils
api手冊地址：http://www.matools.com/api/commons-beanutils
Commons-Fileupload
api手冊地址：http://www.matools.com/api/commons-fileupload
Commons-IO最新版
api手冊地址：http://www.matools.com/api/commons-io
Commons-Lang最新版
api手冊地址：http://www.matools.com/api/commons-long
Commons-Net最新版
api手冊地址：http://www.matools.com/api/commons-net
CSS 3
api手冊地址：http://www.matools.com/api/css
DBCP連接池
api手冊地址：http://www.matools.com/api/dbcp
Dom4j
api手冊地址：http://www.matools.com/api/dom4j
dubbo中文文檔
api手冊地址：http://www.matools.com/api/dubbo
EhCache
api手冊地址：http://www.matools.com/api/ehcache
Freemarker
api手冊地址：http://www.matools.com/api/freemarker
Go語言
api手冊地址：http://www.matools.com/api/go
Hadoop
api手冊地址：http://www.matools.com/api/hadoop
Hibernate中文版
api手冊地址：http://www.matools.com/api/hibernate
IKAnalyzer中文版
api手冊地址：http://www.matools.com/api/ikanalyzer
Java 10
api手冊地址：http://www.matools.com/api/java10
Java 6
api手冊地址：http://www.matools.com/api/java6
Java 7
api手冊地址：http://www.matools.com/api/java7
Java 8中文版
api手冊地址：http://www.matools.com/api/java8
jqGrid中文版
api手冊地址：http://www.matools.com/api/jqgrid
Jquery中文版
api手冊地址：http://www.matools.com/api/jquery
Json-lib
api手冊地址：http://www.matools.com/api/json-lib
Junit4最新版
api手冊地址：http://www.matools.com/api/junit
Kryo
api手冊地址：http://www.matools.com/api/kryo
Log4j最新版
api手冊地址：http://www.matools.com/api/log4j
Lucene
api手冊地址：http://www.matools.com/api/lucene
Maven
api手冊地址：http://www.matools.com/api/maven
Windows MFC中文版
api手冊地址：http://www.matools.com/api/msdn
Mybatis
api手冊地址：http://www.matools.com/api/mybatis
MySql中文版
api手冊地址：http://www.matools.com/api/mysql
Netty 3.6
api手冊地址：http://www.matools.com/api/netty
Nginx中文版
api手冊地址：http://www.matools.com/api/nginx
OpenJPA最新版
api手冊地址：http://www.matools.com/api/openjpa
PHP中文版
api手冊地址：http://www.matools.com/api/php
POI-apache
api手冊地址：http://www.matools.com/api/poi
QuickServer
api手冊地址：http://www.matools.com/api/quickserver
redis中文參考文檔
api手冊地址：http://www.matools.com/api/redis
Ruby
api手冊地址：http://www.matools.com/api/ruby
Ruby-library
api手冊地址：http://www.matools.com/api/ruby-library
Ruby on Rails
api手冊地址：http://www.matools.com/api/rubyonrails
Shiro
api手冊地址：http://www.matools.com/api/shiro
Spring最新版
api手冊地址：http://www.matools.com/api/spring
Spring for Android
api手冊地址：http://www.matools.com/api/spring-android
Spring Boot
api手冊地址：http://www.matools.com/api/spring-boot
Spring Cloud中文文檔
api手冊地址：http://www.matools.com/api/spring-cloud
Spring Security
api手冊地址：http://www.matools.com/api/spring-security
Spring中文版
api手冊地址：http://www.matools.com/api/spring-zh
Struts 2最新版
api手冊地址：http://www.matools.com/api/struts2
Taperstry
api手冊地址：http://www.matools.com/api/taperstry
TensorFlow中文
api手冊地址：http://www.matools.com/api/tensorflow
Tomcat
api手冊地址：http://www.matools.com/api/tomcat
Ubuntu
api手冊地址：http://www.matools.com/api/ubuntu
Velocity 1.7
api手冊地址：http://www.matools.com/api/velocity
VelocityTools2.0
api手冊地址：http://www.matools.com/api/velocity-tools
Vue Router中文參考
api手冊地址：http://www.matools.com/api/vue-router
vue.js中文文檔
api手冊地址：http://www.matools.com/api/vuejs
XMLBeans
api手冊地址：http://www.matools.com/api/xmlbeans
Yahoo UI中文版
api手冊地址：http://www.matools.com/api/yui
Zend Framework中文版
api手冊地址：http://www.matools.com/api/zend-framework
Zookeeper
api手冊地址：http://www.matools.com/api/zookeeper
版權聲明：本文內(nèi)容由網(wǎng)絡用戶投稿，版權歸原作者所有，本站不擁有其著作權，亦不承擔相應法律責任。如果您發(fā)現(xiàn)本站中有涉嫌抄襲或描述失實的內(nèi)容，請聯(lián)系我們jiasou666@gmail.com 處理，核實后本網(wǎng)站將在24小時內(nèi)刪除侵權內(nèi)容。
版權聲明：本文內(nèi)容由網(wǎng)絡用戶投稿，版權歸原作者所有，本站不擁有其著作權，亦不承擔相應法律責任。如果您發(fā)現(xiàn)本站中有涉嫌抄襲或描述失實的內(nèi)容，請聯(lián)系我們jiasou666@gmail.com 處理，核實后本網(wǎng)站將在24小時內(nèi)刪除侵權內(nèi)容。
相關文章
