api在線文檔制作（API制作）

本篇文章給大家談?wù)刟pi在線文檔制作，以及API制作對應(yīng)的知識點(diǎn)，希望對各位有所幫助，不要忘了收藏本站喔。 今天給各位分享api在線文檔制作的知識，其中也會對API制作進(jìn)行解釋，如果能碰巧解決你現(xiàn)在面臨的問題，別忘了關(guān)注本站，現(xiàn)在開始吧！

本文目錄一覽：

• 1、如何快速編寫api文檔
• 2、如何使 WebAPI 自動生成漂亮又實(shí)用在線API文檔
• 3、好用高效的在線文檔編輯工具是哪個？
• 4、自己怎么建API文檔？
• 5、java api接口文檔怎么編寫？
• 6、創(chuàng)業(yè)公司協(xié)同辦公適合用什么在線文檔編輯軟件？

如何快速編寫api文檔

剛開始寫接口文檔的服務(wù)端同學(xué)，很容易按著代碼的思路去編寫接口文檔，這讓客戶端同學(xué)或者是服務(wù)對接方技術(shù)人員經(jīng)常吐槽，看不懂接口文檔。這篇文章提供一個常規(guī)接口文檔的編寫方法，給大家參考。

推薦使用的是docway?寫接口文檔，方便保存和共享，支持導(dǎo)出PDF MARKDOWN，支持團(tuán)隊(duì)項(xiàng)目管理。

一、請求參數(shù)

1. 請求方法

GET

用于獲取數(shù)據(jù)

POST

用于更新數(shù)據(jù)，可與PUT互換，語義上PUT支持冪等

PUT

用于新增數(shù)據(jù)，可與POST互換，語義上PUT支持冪等

DELETE

用于刪除數(shù)據(jù)

其他

其他的請求方法在一般的接口中很少使用。如：PATCH HEAD OPTIONS

2. URL

url表示了接口的請求路徑。路徑中可以包含參數(shù)，稱為地址參數(shù)，如**/user/{id}**，其中id作為一個參數(shù)。

3. HTTP Header

HTTP Header用于此次請求的基礎(chǔ)信息，在接口文檔中以K-V方式展示，其中Content-Type則是一個非常必要的header，它描述的請求體的數(shù)據(jù)類型。

常用的content-type：

application/x-www-form-urlencoded

請求參數(shù)使用“”符號連接。

application/json

內(nèi)容為json格式

application/xml

內(nèi)容為xml格式

multipart/form-data

內(nèi)容為多個數(shù)據(jù)組成，有分隔符隔開

4. HTTP Body

描述http body，依賴于body中具體的數(shù)據(jù)類型。如果body中的數(shù)據(jù)是對象類型。則需要描述對象中字段的名稱、類型、長度、不能為空、默認(rèn)值、說明。以表格的方式來表達(dá)最好。

示例：

二、響應(yīng)參數(shù)

1. 響應(yīng) HTTP Body

響應(yīng)body同請求body一樣，需要描述請清除數(shù)據(jù)的類型。

另外，如果服務(wù)會根據(jù)不同的http status code 返回不同的數(shù)據(jù)結(jié)構(gòu)， 也需要針對不同的http status code對內(nèi)容進(jìn)行描述。

三、接口說明

說明接口的應(yīng)用場景，特別的注意點(diǎn)，比如，接口是否冪等、處理是同步方式還是異步方式等。

四、示例

上個示例（重點(diǎn)都用紅筆圈出來，記牢了）：

五、接口工具

推薦使用的是http://docway.net（以前叫小幺雞） 寫接口文檔，方便保存和共享，支持導(dǎo)出PDF MARKDOWN，支持團(tuán)隊(duì)項(xiàng)目管理。

如何使 WebAPI 自動生成漂亮又實(shí)用在線API文檔

1.1 SwaggerUI
SwaggerUI 是一個簡單的Restful API 測試和文檔工具。簡單、漂亮、易用（官方demo）。通過讀取JSON 配置顯示API. 項(xiàng)目本身僅僅也只依賴一些 html,css.js靜態(tài)文件. 你可以幾乎放在任何Web容器上使用。
1.2 Swashbuckle
Swashbuckle 是.NET類庫,可以將WebAPI所有開放的控制器方法生成對應(yīng)SwaggerUI的JSON配置。再通過SwaggerUI 顯示出來。類庫中已經(jīng)包含SwaggerUI 。所以不需要額外安裝。
2.快速開始
創(chuàng)建項(xiàng)目 OnlineAPI來封裝百度音樂服務(wù)(示例下載) api在線文檔制作，通過API可以搜索、獲取音樂的信息和播放連接。
我盡量刪除一些我們demo中不會用到的一些文件，使其看上去比較簡潔。
WebAPI 安裝 Swashbuckle
Install-Package Swashbuckle
代碼注釋生成文檔說明。
Swashbuckle 是通過生成的XML文件來讀取注釋的，生成 SwaggerUI，JSON 配置中的說明的。
安裝時會在項(xiàng)目目錄 App_Start 文件夾下生成一個 SwaggerConfig.cs 配置文件，用于配置 SwaggerUI 相關(guān)展示行為的。如圖api在線文檔制作：
將配置文件大概99行注釋去掉并修改為
c.IncludeXmlComments(GetXmlCommentsPath(thisAssembly.GetName().Name));
并在當(dāng)前類中添加一個方法
/// <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 文檔文件”，編譯過程中生成類庫的注釋文件
添加百度音樂 3個API
訪問 lt;youhost/swagger/ui/index,最終顯示效果
我們通過API 測試API 是否成功運(yùn)行
3.添加自定義HTTP Header
在開發(fā)移動端 API時常常需要驗(yàn)證權(quán)限，驗(yàn)證參數(shù)放在Http請求頭中是再好不過了。WebAPI配合過濾器驗(yàn)證權(quán)限即可
首先我們需要創(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();
//判斷是否添加權(quán)限過濾器
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權(quán)限過濾器
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)的請求
/// </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 做法類似，只是我們通過特殊的設(shè)置來標(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 配置匿名方法類添加一行注冊代碼
c.OperationFilter<UploadFilter();
API 文檔展示效果

好用高效的在線文檔編輯工具是哪個？

好用高效的在線文檔編輯工具推薦Baklib。

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

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

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

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

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

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

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

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

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

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

在文檔協(xié)作方面，它提供了一個簡潔明了的界面，讓你可以快速創(chuàng)建文檔并共同編輯它們，同時跟蹤以前的版本。多個訪問級別讓你可以完全控制誰可以看到你的內(nèi)容——你可以在線發(fā)布、在內(nèi)部共享、生成通用的可共享 URL 或邀請?zhí)囟ǖ娜恕?/p>

自己怎么建API文檔？

去看看怎么做chm電子書api在線文檔制作的教程吧api在線文檔制作，這不是一個簡單的事。網(wǎng)上也有很多工具，只要你往這個方向前進(jìn)，總能做出來的。
實(shí)際上chm只是一種已經(jīng)過編譯的html文件，在如果是java的api文檔，在eclipse中有自動生成文檔的命令，但生成的是html文件。如果你學(xué)會怎么把這些html編譯成chm，那么這個api文檔不就做出來了嗎api在線文檔制作？

java api接口文檔怎么編寫？

Java語言提供api在線文檔制作了一種強(qiáng)大的注釋形式api在線文檔制作：文檔注釋?？梢詫⒃创a里的文檔注釋提取成一份系統(tǒng)的API文檔。我們在開發(fā)中定義類、方法時可以先添加文檔注釋api在線文檔制作，然后使用javadoc工具來生成自己的API文檔。

文檔注釋以斜線后緊跟兩個星號（/**）開始，以星號后緊跟一個斜線（*/）作為結(jié)尾，中間部分全部都是文檔注釋，會被提取到API文檔中。

自行搜索一下javadoc即可，示例如下：

1234567891011121314151617181920212223242526272829/** * 類描述 * * @author 作者 * @version 版本 */public class DemoClass { ? ?/** ? ? * 內(nèi)部屬性：name ? ? */ ? ?private String name; ? ? ? ? ? /** ? ? * Setter方法 ? ? * @return name ? ? */ ? ?public String getName() { ? ? ? ?return name; ? ?} ? ? /** ? ? * Getter方法 ? ? * @param name ? ? */ ? ?public void setName(String name) { ? ? ? ?this.name = name; ? ?} }

創(chuàng)業(yè)公司協(xié)同辦公適合用什么在線文檔編輯軟件？

api在線文檔制作我們就是創(chuàng)業(yè)公司api在線文檔制作，由于人員比較少，而且資金方面不怎么充裕，所以在選擇協(xié)同辦公api在線文檔制作的在線文檔編輯軟件時，我們希望盡量選擇功能較為豐富的、使用方便的高性價比軟件。網(wǎng)上比較火的有石墨文檔、億方云等等，使用體驗(yàn)api在線文檔制作了一圈下來，我們覺得還是億方云比較適合我們公司。首先是因?yàn)閮|方云支持預(yù)覽的格式更多，億方云支持100多種格式文件在線預(yù)覽，包括一般Office文檔、PDF文件、圖片格式，及CAD、Photoshop、AI、Project、Visio等專業(yè)格式，不用額外安裝任何插件；而石墨文檔只支持word、excel、ppt等常規(guī)格式的預(yù)覽，不支持CAD、Photoshop、AI這類專業(yè)格式。其次是億方云的多人同時在線編輯功能更豐富，支持web端、客戶端、移動端三端多人同時在線編輯word、excel、PPT、PDF格式文件；而石墨文檔只有網(wǎng)頁端和移動端支持多人同時在線編輯文檔、表格、幻燈片等文件，文檔、表格、幻燈片文件格式還是石墨文檔的專有格式，導(dǎo)入導(dǎo)出都需要轉(zhuǎn)換格式，又要多費(fèi)一番功夫。此外，億方云還支持文件（夾）評論和語音評論（移動端），可@全員，也可@某人，還支持消息提醒，可以替代一部分即時通訊軟件和郵箱的功能；而石墨文檔僅支持石墨專有格式（文檔、表格、思維導(dǎo)圖）文件進(jìn)入文件編輯模式時評論，功能并不完善。所以綜合考慮下來，我司還是決定選擇億方云。 關(guān)于api在線文檔制作和API制作的介紹到此就結(jié)束了，不知道你從中找到你需要的信息了嗎 ？如果你還想了解更多這方面的信息，記得收藏關(guān)注本站。 api在線文檔制作的介紹就聊到這里吧，感謝你花時間閱讀本站內(nèi)容，更多關(guān)于API制作、api在線文檔制作的信息別忘了在本站進(jìn)行查找喔。

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

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