api文件製作

Ⅰ 如何快速編寫api文檔

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

推薦使用的是docway寫介面文檔，方便保存和共享，支持導出PDF MARKDOWN，支持團隊項目管理。

一、請求參數

1. 請求方法

• GET

用於獲取數據

• POST

用於更新數據，可與PUT互換，語義上PUT支持冪等

• PUT

用於新增數據，可與POST互換，語義上PUT支持冪等

• DELETE

用於刪除數據

• 其他

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

2. URL

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

3. HTTP Header

HTTP Header用於此次請求的基礎信息，在介面文檔中以K-V方式展示，其中Content-Type則是一個非常必要的header，它描述的請求體的數據類型。

常用的content-type：

• application/x-www-form-urlencoded

請求參數使用「&」符號連接。

• application/json

內容為json格式

• application/xml

內容為xml格式

• multipart/form-data

內容為多個數據組成，有分隔符隔開

4. HTTP Body

描述http body，依賴於body中具體的數據類型。如果body中的數據是對象類型。則需要描述對象中欄位的名稱、類型、長度、不能為空、默認值、說明。以表格的方式來表達最好。

示例：



五、介面工具

推薦使用的是http://docway.net（以前叫小幺雞） 寫介面文檔，方便保存和共享，支持導出PDF MARKDOWN，支持團隊項目管理。

Ⅱ 如何使 WebAPI 自動生成漂亮又實用在線API文檔

1.1 SwaggerUI

SwaggerUI 是一個簡單的Restful API 測試和文檔工具。簡單、漂亮、易用（官方demo）。通過讀取JSON 配置顯示API. 項目本身僅僅也只依賴一些 html,css.js靜態文件. 你可以幾乎放在任何Web容器上使用。

1.2 Swashbuckle

Swashbuckle 是.NET類庫,可以將WebAPI所有開放的控制器方法生成對應SwaggerUI的JSON配置。再通過SwaggerUI 顯示出來。類庫中已經包含SwaggerUI 。所以不需要額外安裝。

2.快速開始

創建項目 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

訪問 http://<youhost>/swagger/ui/index,最終顯示效果

我們通過API 測試API 是否成功運行

3.添加自定義HTTP Header

在開發移動端 API時常常需要驗證許可權，驗證參數放在Http請求頭中是再好不過了。WebAPI配合過濾器驗證許可權即可

首先我們需要創建一個 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.顯示上傳文件參數

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 文檔展示效果

Ⅲ ApiPost 快速生成在線介面文檔!!

探索ApiPost：在線介面文檔生成神器，助你輕松開發與管理

ApiPost，一款專為API開發者和測試人員量身打造的高效工具，它不僅具備強大的調試功能，還提供一鍵生成美觀、易讀的在線文檔，讓團隊協作變得更加順暢。無論是後台介面開發者還是前端工程師，它都能成為你的得力助手。

一、Apipost的全能魅力

ApiPost不僅支持POST、GET、PUT等常見的HTTP請求模擬，還內置了文檔編寫功能，讓你在調試介面的同時，輕松撰寫詳細的注釋，生成出專業級別的在線文檔。通過直觀的界面，你可以快速上手並掌握其基本操作。

二、下載與安裝

下載Apipost非常簡單，只需訪問官方網站（無需贅述鏈接），根據你的操作系統（Windows、Mac或Linux）下載對應的安裝包，幾分鍾就能搞定。官方文檔詳盡豐富，助你無縫集成到開發流程中。

三、常用操作詳解

初次使用Apipost，你需要注冊並創建項目，通過左側菜單輕松進入API控制台。除了基礎的介面發送和文檔生成，還有更多實用功能等你探索。例如，導入參數時，無論是key-value還是JSON格式，Apipost都能快速處理，大大節省時間。

四、操作技巧分享

1. 參數導入便捷 - Apipost支持一鍵導入請求頭、查詢參數和body的參數，無論是瀏覽器控制台的格式還是JSON格式，只需一鍵導入，無需逐個輸入。

2. 智能參數注釋 - 參數描述自動識別和保存，減少重復勞動。只需為參數添加一次注釋，後續遇到相同參數時，Apipost會自動提示，讓文檔編寫更加高效。

3. 定位介面目錄 - 利用"定位到當前介面目錄"功能，輕松找到工作中的介面文件，提高開發效率。

4. 在線文檔生成與分享 - 新版Apipost支持一鍵生成並分享文檔，設置鏈接許可權和有效期，方便他人查看和協作。

結語：發現更多實用小功能

這只是Apipost眾多實用功能的冰山一角，它還提供了更多貼心的設計，例如快速克隆項目、支持RESTful風格的路徑變數等，幫助你更好地管理和優化介面開發。趕快下載Apipost，讓介面文檔生成和管理變得輕松愉快吧！