开启掘金成长之旅！这是我参与「掘金日新计划 · 12 月更文挑战」的第7天，点击查看活动详情
前言
本文主要介绍项目接口文档的使用，目前大约有80个接口，采用 restful api 风格，接口文档未使用现有的工具，而是根据项目的实际情况，开发了一个文档管理网站，便于接口浏览与调试。
接口文档地址：慕影网移动端接口文档
一、 接口介绍
1. 接口风格
-
项目所有接口均采用
restful api风格，即：/{resources}/{resource_id}/{subresources}/{subresource_id} -
本项目支持的
HTTP请求方法HTTP Method 幂等性 鉴权 说明 GET 幂等 部分鉴权 获取信息，大部分接口可直接访问 POST 非幂等 鉴权 表单提交，除登录接口外，一般会生成一条记录 PUT 幂等 鉴权 内容编辑 DELETE 幂等 鉴权 内容删除 -
接口示例
API Name API Method API URL Path 获取所有评论 GET /comments 获取某条评论 GET /comments/{comment_id} 发布评论 POST /comments 编辑评论 PUT /comments/{comment_id} 删除评论 DELETE /comments/{comment_id}
2. content-type
HTTP 请求的 header 中的 Content-Type 用于告诉客户端接口返回的内容类型。作为接口，常用的形式有如下几种：
| Content-Type | 说明 |
|---|---|
| application/json | JSON数据格式 |
| application/x-www-form-urlencoded | 表单类型，key/value格式 |
| multipart/form-data | 表单文件上传 |
本项目除上传外所有接口均使用 application/json 形式，wx.request 的默认格式也是这个，所以所有接口均省略该类型的传值。
3. 返回数据
-
状态码
本项目主体是按照HTTP状态码返回数接口状态的，主要涉及到以下几种状态码（对于前端来说，实际使用时并不是很合适） | 状态码 | 状态码英文名称 | 说明 | | --- | --- | --- | | 200 | OK | 成功 | | 401 | Unauthorized | 用户身份认证失败，如未登录发布评论 | | 403 | Forbidden | 服务端拒绝执行，一般是无权限，如删除他人评论 | | 404 | Not Found | 接口不存在 | | 405 | Method Not Allowed | 请求方法错误，如 post 写成 get | | 500 | Internal Server Error | 服务器内部错误 | -
业务状态码
本项目中接口请求成功后，返回的HTTP状态码一般就是200，返回数据中根据业务又加入了一层内部状态码：code message 200 成功 403 无访问权限 404 您访问的资源不存在 409 该资源已存在 410 该资源已被删除 422 请求参数错误 -
数据格式
字段 类型 描述 code Number 接口业务状态 data Object/Array 返回数据格式 message String 接口业务信息 total Number 当接口有分页时，会返回数据总条数
二、文档界面介绍
以下是接口文档的使用介绍，操作挺简单，左侧是接口分类，右侧是接口内容。
1. 接口文档 Readme 页面功能分区
2. 接口详情页介绍
3. 接口请求示例
4. 需要鉴权接口
如果当前接口需要登录，则点击确定按钮跳转到登录的接口页，会有默认账户信息，登录后会记录下该账号的 token ，需要鉴权的接口会自动携带该 token 信息。
再次调用登录接口，会覆盖上次登录信息。
5. 登录获取 token 信息
最后
以上即为本项目的接口文档介绍，同时粗略的介绍了 restful api 与 http 状态码，日常业务中的接口设计大体如此，由于我并非专业后端，受前端思想的影响，在有些接口设计上存在欠缺，欢迎评论探讨。
