常用接口文档模板

接口规范说起来大,其实也就那么几个部分,接口规范、接口管理工具、接口文档编写、开发文档编写。以下将详细介绍,下面进入正文:

接口规范文档

具体内容如下:

一:协议规范

二:域名规范

三:版本控制规范

四:API路径规范

五:API命名规范

六:请求参数规范

七:列表请求特殊规范

八:返回数据规范

九:接口文档规范

十:接口管理工具使用教程


参与编写

更新日期

版本

备注

AbyssKitty

2018/04/06

V1.1.0

V1.1.0更新日志:

1. 新增协议规范、域名规范、版本控制规范、列表特殊规范。

2. 更新接口管理工具使用教程。

3. 美化排版。

正文:

一:协议规范

为进一步确保数据交互安全。正式地址(生产地址)必须遵循HTTPS协议。

二:域名规范

每个项目要有且仅有一个自己唯一的域名+端口。在项目配置文件中要添加静态变量专门进行存储。

如果一个域名满足不了要求,那么就需要再添加一个。

格式规范如下:

(java)public static final String URL_BASE = “https://127.0.0.1:8080/”;

(java)public static final String URL_BASE_SUB = “https://192.168.0.1:8080/”;

必须以https开头,并以“/”结尾。

三:API路径规范

作为接口路径,为了和其他路径完美区分,必须在路径中添加api目录

格式规范如下:

(java)public static final String URL_API = “api/”;

(PHP)php目录是加index.php/api/

必须以字母开头,并以“/”结尾。

四:版本控制规范

项目正式上线后,正式版本要确定接口版本、并备份接口代码。

为方便管理,需要在接口路径中加入版本号信息。

格式规范如下:

(java)public static final String URL_VERSION =”v1/”;

必须以字母开头,并以“/”结尾。

更新版本后可以使用v2 v3等、依次递加。

五:API命名规范

根据二:域名规范、三:API路径规范、四:版本控制规范。项目中必须在配置文件中增加BaseUrl静态常量。值=三个相加。

格式规范如下:

(java)public static final String BASEURL=URL_BASE+URL_API+URL_VERSION;

具体代码如下:

BASEURL = [“https://127.0.0.1:8080/api/v1/”]

BASEURL = [“https://127.0.0.1:8080/api/v1/”]

BASEURL = [“https://127.0.0.1:8080/api/v1/”]

重要的事情说三遍。

根据业务需求,可以在v1版本文件夹里创建,一个或者多个接口文件。

一个的规范:

https://127.0.0.1:8080/api/v1/getBanner

这就是一个获取banner的接口。

多个的规范是根据业务需求来区分:

https://127.0.0.1:8080/api/v1/home/getBanner

https://127.0.0.1:8080/api/v1/user/userLogin

新建user文件,里面存放用户级别的操作:如登陆、注册、修改密码等等。

新建sms文件,里面存放对短信的接口操作:如发送验证码、验证手机号等等。

所以,接口方法文件必须要有自己的规范,命名必须统一使用驼峰命名法或者下划线拼接命名法。举个栗子:(upperCamelCase)(upper_camel_case)。所有接口命名方式,必须遵循如下规范。

(1)新增方法:如新增一个地址、新增一个联系人。

命名规范:

必须以“add”为前缀。例如addAddress

事例地址:https://127.0.0.1:8080/api/v1/addAddress

(2)删除方法:如删除一个地址。

命名规范:

必须以“delete”为前缀。例如deleteAddress

事例地址:https://127.0.0.1:8080/api/v1/deleteAddress

(3)修改方法:如修改一个地址。

命名规范:

必须以“updata”为前缀。例如updataAddress

事例地址:https://127.0.0.1:8080/api/v1/updataAddress

(4)获取方法:如获取一个地址。

命名规范:

必须以“get”为前缀。例如getAddress

事例地址:https://127.0.0.1:8080/api/v1/getAddress

(5)获取列表方法:如获取一个地址列表。

命名规范:

必须以“get”为前缀、“List”为后缀。例如getAddressList

事例地址:https://127.0.0.1:8080/api/v1/getAddressList

其他规范:

发送验证码使用‘send’为前缀、保存一个数据以‘save’为前缀、上传图片以‘uploadImage’为名称等等。

具体地址就等于(BASEURL+“address/getAddressList”)

目的:一目了然、降低维护成本。

六:请求参数规范

请求方式:公共数据使用get方式请求,私有数据使用post方式请求。尽量全部是用post。

请求头:请求头根据项目需求添加配置参数。如:accept=‘application/json

’等。请求头根据项目需求可以要求传入用户token、app名称版本、唯一验签码等加密数据。

请求参数:

根据数据库字段进行命名、保持一致最省事。

七:列表请求特殊规范

列表请求,请求参数规范,必须传参:页数和每页个数的字段。并可包含查询等信息。

1. 列表接口必传字段(分页、使用小写字母)。

page :页数,从1开始。例如:{ “page”: 1  }

subnumber : 每页数量。

2. 列表接口选传字段。

只要是列表接口、一般情况下都会存在检索条件,例如淘宝商品检索。检索条件为选填。

后台需进行非空非null判断,选传字段为空为null默认查询全部。有值则需要接收,并进行sql查询。

规范事例:

普通列表接口:https://127.0.0.1:8080/api/v1/getBannerList

(不传page、后台默认返回全部数据)

(banner接口不需要使用检索条件)

需检索列表接口:https://127.0.0.1:8080/api/v1/getOrderList

(不传page、后台默认返回全部数据)

(Order订单接口需要检索条件,不传就不检索,只进行分页查询)

(如果有 time price等检索条件,不传就不检索,传了就进行条件查询,并返回相应数据)

八:返回数据规范

注:列表数据返回,没有特殊情况的条件下,必须最新数据在上面,依次排序。

返回事例:

{

"list":[],

"object":{}, //"object":""

"status":"SUCCESS",

"message":"我是提示消息",

...

"page":1,

"subnumber":10,

}

必选-命名规范:驼峰命名法。

必选-新增键值规则:名字对应固定的格式(list就是数组[])。

举个栗子:比如一个"list":[]满足不了需求,那么可以新增一个"map":[]。

比如一个"object":{"name":"小明"}满足不了需求,那么可以新增一个"details":{"name":"小红"}。名字对应固定的格式,数组就是数组、实体类就是实体类、字段就是字段。不能data在这个接口返回的是实体类、另一个接口又返回数组了。需要特别注意。

必选-list:list列表(数组)为空时显示[]。

必选-object:实体数据,json键值对。

必选-status:状态信息=SUCCESS、ERROR等静态变量。

必选-message:提示消息。(加载成功、)

可选-page:页数(分页查新时使用、显示第几页从一开始)。

可选-subnumber:每页的格式(分页查询时使用、显示当前页的个数)。

九:接口文档规范

接口文档需要包含以下部分:

文档名称。

版本号。

编写人。

编写、修改日期。

baseUrl地址。

更新日志。

接口详情。(详情规范如下)

接口详情编辑规范:

一个完整的接口需要由以下几部分组成

1.请求地址 例如:https://127.0.0.1:8080/xxx/xxx/xxx

2.请求方式 例如:POST、GET等

3.请求参数 例如:传 id:“1”,name:“小明”

4.返回参数 例如:{ json... } 【参考上面的接口规范】

5.返回事例 例如:{ json... }

十:接口管理工具使用教程

接口管理工具有很多,例如RAP、eolinker等等。

接口管理工具基本的作用都是用来管理接口的。这里简单介绍eolinker的使用方法。

使用方法步骤:

创建接口管理项目。

邀请开发者同事加入。

编写接口(接口地址、请求参数及备注、请求方式、返回参数及备注、返回事例、在线测试接口)。

开发者使用接口。

过程中灵活配合,接口可以灵活更新。

完成项目后可以导出接口文档。

1. 查询指定项目属性

接口功能
获取制定项目的分类信息

URL
http://www.api.com/index.php

支持格式
JSON

HTTP请求方式
GET

请求参数
参数 必选 类型 说明
name ture string 请求的项目名
type true int 请求项目的类型。1:类型一;2:类型二 。
返回字段
返回字段 字段类型 说明
status int 返回结果状态。0:正常;1:错误。
company string 所属公司名
category string 所属类型
接口示例
地址:http://www.api.com/index.php?name=”可口可乐”&type=1

{
"statue": 0,
"company": "可口可乐",
"category": "饮料",
}
1
2
3
4
5
markdown源码如下:

目录

1\. 查询指定项目属性接口

---

**1\. 查询指定项目属性**
###### 接口功能
> 获取制定项目的分类信息

###### URL
> [http://www.api.com/index.php](www.api.com/index.php)

###### 支持格式
> JSON

###### HTTP请求方式
> GET

###### 请求参数
> |参数|必选|类型|说明|
|:----- |:-------|:-----|----- |
|name |ture |string|请求的项目名 |
|type |true |int |请求项目的类型。1:类型一;2:类型二 。|

###### 返回字段
> |返回字段|字段类型|说明 |
|:----- |:------|:----------------------------- |
|status |int |返回结果状态。0:正常;1:错误。 |
|company |string | 所属公司名 |
|category |string |所属类型 |

###### 接口示例
> 地址:[http://www.api.com/index.php?name="可口可乐"&type=1](http://www.api.com/index.php?name="可口可乐"&type=1)
``` javascript
{
"statue": 0,
"company": "可口可乐",
"category": "饮料",
}
---------------------

原文地址:https://www.cnblogs.com/klb561/p/10066783.html

时间: 2024-10-09 06:27:11

常用接口文档模板的相关文章

接口文档模板(Markdown)

效果 目录 1. 查询指定项目属性接口 1. 查询指定项目属性 接口功能 获取制定项目的分类信息 URL http://www.api.com/index.php 支持格式 JSON HTTP请求方式 GET 请求参数 > 参数 必选 类型 name ture string 请求的项目名 type true int 请求项目的类型.1:类型一:2:类型二 . 返回字段 > 返回字段 字段类型 status int 返回结果状态.0:正常:1:错误. company string 所属公司名 c

markdown格式接口文档模板

目录 测试接口 查询指定项目属性** 接口功能 获取制定项目的分类信息 接口地址 https://www.bincoding.cn/test HTTP请求方式 POST JSON 请求参数 参数 必选 类型 说明 name ture string 请求内容1 type true int 请求内容2 返回字段 返回字段 字段类型 说明 code int 返回状态,0 成功, 9失败 msg string 成功/失败提示 data string 响应内容 接口示例 地址:https://www.bi

附录1:接口文档参考模板

https://www.w3cschool.cn/phalapi/5fhi1tth.html 附录1:接口文档参考模板 由 chanzonghuang 创建,最后一次修改 2016-11-20 虽然提供了在线接口参数的查看,但在和客户端对接过程中,我们作为后台开发,还是需要人工提供接口文档给客户端的,这里提供一个接口文档编写的模板,以供参考,并且以我们熟悉的?service=User.GetBaseInfo为例说明如何编写高效的文档. 温馨提示:斜体字表示是注释说明. 功能说明 对接口功能的简单

如何利用apidoc来写接口文档

在开发后台接口的过程中,肯定要提供一份api接口文档给终端.一直用word写,太丑了..怎么才能做出一份漂亮的api文档呢?找了好久发现了今天的主角-apidoc. 官网地址:http://apidocjs.com 开放API已经成为当下主流平台的一个要素,特别对于社交.电商类的平台开放API更成为了竞争力的一种.开放API文档的完整性.可阅读性往往影响着接入方是否能顺利地.快速地接入到平台,一份好的.统一的API文档也是开放平台不可或缺的要素. apidoc是通过源码中的注释来生成API文档,

接口文档

什么是接口文档? 在项目开发中,web项目的前后端分离开发,APP开发,需要由前后端工程师共同定义接口,编写接口文档,之后大家都根据这个接口文档进行开发,到项目结束前都要一直维护. 为什么要使用接口文档? 1.项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发. 2.项目维护中或者项目人员更迭,方便后期人员查看.维护. 接口文档的核心是什么? 接口核心分为四个部分: 请求方法. uri.请求参数.返回参数. 请求方法: 即请求的方法是什么.常用的请求方法有get.post.delete.

[API]使用Blueprint来高雅的编写接口文档

Blueprint(http://apiary.io/)是apiary公司的工具包,用来编写API文档,类似于Markdown,是一种标记语言. 对于习惯使用RESTful API的同志们来说,使用Blueprint可以快速的写出高雅大气的文档: 下面以一个Github中的Gist服务为例,简单的演示一下Blueprint的应用. 原文地址:http://blog.callmewhy.com/2014/06/05/blueprint-tutorial/ API Blueprint是一套API描述

接口文档要如何写

一个简单的接口文档,写完给组长看后,发现漏洞百出.下面总结一下写文档需要注意事项:        封皮 封面最好是本公司规定的封面,有logo,内容标题,版本号,公司名称,文档产生日期.(错误地方在于,文档的标题要和页眉中的标题一致)        修订历史 表格形式较好些.包括,版本,修订说明,修订日期,修订人,审核时间审核人.(我错误的地方在于,表格中其他空白表格没有居中)        接口信息 接口调用方式,是post方式还是get方式,接口地址,别人需要线上的哪个地址就写哪个.(自己提

开发接口文档--本接口文档是读取控制器方法上的注释自动生成的

本文档是参考网上的然后根据公司需要对代码进行了抽取和优化(主要是加了标题栏和对输出进行了格式化输出,更换呢了页面渲染方式(改为直接使用php进行渲染,原来的是使用了模板引擎),可读性较好),配置简单,读取方便,和项目耦合性较小,只需要将api_view这个文件夹放到和项目同级就可以使用,接口文档只有100多k大小 1.配置控制器 按照上图格式写接口方法注释(主是在控制器上面和方法上) 2.将接口文档放置在和项目同级 注:上面3个事项目,最下面的是接口文档 3.配置接口文档配置文件 api_vie

给WebApi添加SwaggerUI,生成可交互接口文档

在ABP模板项目中,通过SwaggerUI可以为我们的WebApi生成动态的可交互接口文档页面,从而很方便的测试调用我们的WebApi接口. 1.集成Swagger 右键项目YoYo.Web,打开NuGet程序包管理器,添加Swashbuckle. 其中包含了程序和UI,安装后在App_Start文件夹下生成SwaggerConfig.cs. 完成这一步,Swagger已经集成完毕. 可以访问http://localhost:XXXX/swagger/ui/index. 如果出现异常,可以先尝试