前端api接口文档示例（前端接口文档怎么用）

本篇文章给大家谈谈前端api接口文档示例，以及前端接口文档怎么用对应的知识点，希望对各位有所帮助，不要忘了收藏本站喔。 今天给各位分享前端api接口文档示例的知识，其中也会对前端接口文档怎么用进行解释，如果能碰巧解决你现在面临的问题，别忘了关注本站，现在开始吧！

本文目录一览：

• 1、使用 API Blueprint 来编写 API 接口文档
• 2、前端文档接口怎么写
• 3、Restful接口文档规范
• 4、开放平台API接口安全性设计——微信支付为例
• 5、前端模拟后端接口返回数据常用的三种方法

使用 API Blueprint 来编写 API 接口文档

API Blueprint 用来编写API文档的一种标记语言，类似于Markdown，具体的语法规则可以在 API Blueprint documentation 查看，文档里面还有一个简短的 API Blueprint tutorial 建议先仔细阅读一下这个教程。

使用 API Blueprint 文档，配合一些开源的工具可以把接口文档渲染成 html 再搭配一个静态服务器，就可以很方便的共享给同事。

相对于 word 这种富文本格式的文档来说， API Blueprint 是纯文本，这样可以很方便的使用版本控制工具 Git 来控制版本。

另外，配合一些工具，可以直接生成一个 mock data 数据，这样只要和后端的同学约定好接口格式，那么前端再开发的时候可以使用 mock data 数据来做测试，等到后端写好接口之后再做联调就可以了。

API Blueprint 社区提供了一些文本编辑器的插件，可以识别 API Blueprint 语法支持语法高亮。

使用 apiblueprint 编写好文档使用，可以使用开源社区提供的一个工具 aglio 来把接口文档渲染成 html 文件， aglio 还会启动一个静态服务器，这样就可以在浏览器里面查看渲染好的文档了。

aglio 的使用教程，可以直接查看官方开发仓库的 readme 文档。另外，这里也有一份资料 使用API-Blueprint 编写 API 文档 可以参考。

前端文档接口怎么写

1.先上一个案例

a.接口名称如果是获取天气预报那么应该突出“获取”，第一个单词应该是动词,for example:get

b.采用小驼峰命名法

c.接口地址是后端人员编写的，这行就不要写了

d.参数和返回的数据一律小写

e.如果返回值有图片地址的话，应该是个路径而不是图片名  for exampl：picname:"./file/weather/real.jpg"

Restful接口文档规范

基于目前的大前端时代，对于常年负责后台开发的我来说， 最重要的就是提供稳定的接口和文档。便于小伙伴们进行业务对接。

当下常用的是RestFul风格的定义规范， 之前开发是清一色Get、Post。引入RestFul后感觉接口定义规范很多，看接口地址就知晓是什么功能， 一起来看看列的一些基础规范吧。
API与客户端用户的通信协议，总是使用HTTPS协议，以确保交互数据的传输安全。
应该尽量将API部署在专用域名之下： https://api.example.com

如果确定API很简单,不会有进一步扩展,可以考虑放在主域名下： https://www.example.com/api
https://api.example.com/v{n}

1、应该将API的版本号放入URL。

2、采用多版本并存，增量发布的方式。

3、n代表版本号，分为整型和浮点型

整型： 大功能版本， 如v1、v2、v3 ...

浮点型： 补充功能版本， 如v1.1、v1.2、v2.1、v2.2 ...

4、对于一个 API 或服务，应在生产中最多保留 3 个最详细的版本
路径又称"终点"（end point），表示API的具体网址。

1、在RESTful架构中，每个网址代表一种资源(resource),所以网址中不能有动词，只能有名词。

【所用的名词往往与数据库的表格名对应】

2、数据库中的表一般都是同种记录的"集合"(collection),所以API中的名词也应该使用复数。

例子: https://api.example.com/v1/products

https://api.example.com/v1/users

https://api.example.com/v1/employees
GET（SELECT）： 从服务器取出资源（一项或多项）。

POST（CREATE）： 在服务器新建一个资源。

PUT（UPDATE）： 在服务器更新资源（客户端提供改变后的完整资源）。

DELETE（DELETE）： 从服务器删除资源。

例子：

GET /v1/products 获取所有商品

GET /v1/products/ID 获取某个指定商品的信息

POST /v1/products 新建一个商品

PUT /v1/products/ID 更新某个指定商品的信息

DELETE /v1/products/ID 删除某个商品,更合理的设计详见【9、非RESTful API的需求】

GET /v1/products/ID/purchases 列出某个指定商品的所有投资者

GET /v1/products/ID/purchases/ID 获取某个指定商品的指定投资者信息
若记录数量很多，服务器不可能返回全部记录给用户。

API应该提供分页参数及其它筛选参数，过滤返回结果。

/v1/products?page=1pageSize=20 指定第几页，以及每页的记录数。

/v1/products?sortBy=nameℴ=asc 指定返回结果按照哪个属性排序，以及排序顺序。
传入参数分为4种类型：

1、cookie： 一般用于OAuth认证

2、request header： 一般用于OAuth认证

3、请求body数据：

4、地址栏参数：

1）restful 地址栏参数 /v1/products/ID ID为产品编号，获取产品编号为ID的信息

2）get方式的查询字段 见【六、过滤信息】
response：

----------------------------------------

{

status: 200, // 详见【status】

data: {

code: 1, // 详见【code】

data: {} || [], // 数据

message: '成功', // 存放响应信息提示,显示给客户端用户【须语义化中文提示】

sysMessage: 'success' // 存放响应信息提示,调试使用,中英文都行

... // 其它参数，如 total【总记录数】等

},

msg: '成功', // 存放响应信息提示,显示给客户端用户【须语义化中文提示】

sysMsg: 'success' // 存放响应信息提示,调试使用,中英文都行

}

----------------------------------------

【status】:

200: OK 400: Bad Request 500：Internal Server Error

401：Unauthorized

403：Forbidden

404：Not Found

【code】:

1: 获取数据成功 | 操作成功 0：获取数据失败 | 操作失败
1、实际业务开展过程中，可能会出现各种的api不是简单的restful 规范能实现的。

2、需要有一些api突破restful规范原则。

3、特别是移动互联网的api设计，更需要有一些特定的api来优化数据请求的交互。

1)、删除单个 | 批量删除 ： DELETE /v1/product body参数{ids：[]}

2)、页面级API : 把当前页面中需要用到的所有数据通过一个接口一次性返回全部数据
1、前端需要哪些字段，API接口应该返回哪些字段，字段不多也不少。

2、更新功能尽量做到：初次返回的原始数据参数与提交更新的数据参数结构一致。

3、时间参数，尽量以一致格式的字符串传递， 如：

‘2019-01’ | ‘2019/01’

‘2019-01-01’ | ‘2019/01/01’

‘2019-01-01 12:12:12’ | ‘2019/01/01 12:12:12’
1、尽量采用自动化接口文档，可以做到在线测试，同步更新。

2、应包含：接口BASE地址、接口版本、接口模块分类等。

3、每个接口应包含：

接口地址：不包含接口BASE地址。

请求方式: get、post、put、delete等。

请求参数：数据格式【默认JSON、可选form data】、数据类型、是否必填、中文描述。

相应参数：类型、中文描述。

开放平台API接口安全性设计——微信支付为例

API接口，类似 http://mypay.com/refund/order_id=123mch_id=123 ，这个请求前端api接口文档示例我以商户mch_id=123的身份给订单号为order_id=123退款，如果服务器不辩别请求发起者的身份直接做相应的操作，那是及其危险的。

一般的，在PC端，我们是通过加密的cookie来做会员的辨识和维持会话的；但是cookie是属于浏览器的本地存储功能。APP端不能用，所以我们得通过token参数来辨识会员；而这个token该如何处理呢？
延伸开来，接口的安全性主要围绕Token、Timestamp和Sign三个机制展开设计，保证接口的数据不会被篡改和重复调用。

一般来说，在前端对数据做加密或者前面，是不现实的。前后端使用HTTP协议进行交互的时候，由于HTTP报文为明文，所以通常情况下对于比较敏感的信息可以通过在前端加密，然后在后端解密实现"混淆"的效果，避免在传输过程中敏感信息的泄露（如，密码，证件信息等）。不过前端加密只能保证传输过程中信息是‘混淆’过的，对于高手来说，打个debugger，照样可以获取到数据，并不安全，所谓的前端加密只是稍微增加了攻击者的成本，并不能保证真正的安全。即使你说在前端做了RSA公钥加密，也很有可能被高手获取到公钥，并使用该公钥加密数据后发给服务端，所以务必认为前端的数据是不可靠的，服务端要加以辩别。敏感信息建议上https。

所以一般建议上https，敏感信息md5混淆，前端不传输金额字段，而是传递商品id，后端取商品id对应的金额，将金额等参数加签名发送到支付系统。金额可以是明文的。

token授权机制 ：用户使用用户名密码登录后，后台给客户端返回一个token（通常是UUID），并将Token-UserId键值对存储在redis中，以后客户端每次请求带上token，服务端获取到对应的UserId进行操作。如果Token不存在，说明请求无效。
弊端 ：token可以被抓包获取，无法预防MITM中间人攻击

用户每次请求都带上当前时间的时间戳timestamp，服务器收到请求后对比时间差，超过一定时长（如5分钟），则认为请求失效。时间戳超时机制是防御DOS攻击的有效手段。

将token，timestamp等其前端api接口文档示例他参数以字典序排序，再加上一个客户端私密的唯一id（这种一般做在服务端，前端无法安全保存这个id）或使用私钥签名，将前面的字符串做MD5等加密，作为sign参数传递给服务端。

地球上最重要的加密算法：非对称加密的RSA算法。公钥加密的数据，可以用私钥解密；私钥签名（加密）的数据，可以用公钥验签。

RSA原理是对极大整数做因数分解，以下摘自维基百科。

暂时比较忙没时间，将于7月29日晚更新。
来更新啦。
微信支付安全规范，可以查看官方文档 https://pay.weixin.qq.com/wiki/doc/api/jsapi.php?chapter=4_3
第1点中，其签名算法最重要的一步，是在最后拼接了商户私密的API密钥，然后通过md5生成签名，这时即使金额是明文也是安全的，如果有人获取并修改了金额，但是签名字段他是无法伪造的，因为他无法知道商户的API密钥。当然，除了微信支付的拼接API生成签名的方法，我们也可以通过java自带的security包进行私钥签名。其中nonce随机字符串，微信支付应该做了校验，可以防止重放攻击，保证一次请求有效，如果nonce在微信支付那边已经存在，说明该请求已执行过，拒绝执行该请求。

阮一峰老师的博客-RSA算法原理： http://www.ruanyifeng.com/blog/2013/07/rsa_algorithm_part_two.html
维基百科： https://zh.wikipedia.org/wiki/RSA%E5%8A%A0%E5%AF%86%E6%BC%94%E7%AE%97%E6%B3%95

前端模拟后端接口返回数据常用的三种方法

官网 gitHub源码地址

使用方法：在模板数据中定义参数,值为@加上对应的占位符用引号引起来，比如 'nowTime':'@now' ,请求返回的数据就是当前发送请求时的时间 "2017-09-02 11:42:06"；下面我使用了三个占位符，

页面显示：

这里简单介绍一下mockjs怎么使用的，想了解更详细的使用，请参 考官方文档 和 官方示例 ，写的很详细，这里就不多说了还有 Mock.valid( template, data ) 效验真实数据的方法，个人觉得用的不多，想了解的自行查看文档。

官网

成功后会自动在目标位置创建一个名为myapp的项目并生成很多文件，命令行显示效果如下：

在命令行最下面有提示， install dependencies: cd myapp npm install 然后 run the app: npm start ,我们按照提示来；

在项目下新建一个config文件夹并新建一个 api.js ,配置一下：

最后附源码 GitHub地址 关于前端api接口文档示例和前端接口文档怎么用的介绍到此就结束了，不知道你从中找到你需要的信息了吗 ？如果你还想了解更多这方面的信息，记得收藏关注本站。 前端api接口文档示例的介绍就聊到这里吧，感谢你花时间阅读本站内容，更多关于前端接口文档怎么用、前端api接口文档示例的信息别忘了在本站进行查找喔。

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。