写好 API 接口文档,想清楚这几点

article/2025/9/11 20:52:57

我在开始一个新的接口之前,需要进行以下判断:

  1. 请求协议是不是 HTTP、https?

  2. 请求体和响应格式是什么(XML、JSON、FormData、Raw)?

  3. API 是不是 RESTful 风格?

如果上面三个问题的答案都清楚了,就可以开始新增一个 API 接口。

API 信息

在编辑 API 的顶部填写 API 的请求协议、方式、地址、名称;

协议支持

  • HTTP/HTTPS

请求方式支持

  • POST

  • GET

  • PUT

  • DELETE

  • HEAD

  • OPTIONS

  • PATCH

API 请求参数

设置请求头部

你可以输入或导入请求头部。

除了手动输入,你还可以批量导入请求头部,数据格式为key:value,一行一条header信息,如:

Connection: keep-alive
Content-Encoding: gzip
Content-Type: application/json
Date: Mon, 30 Dec 2019 20:49:45 GMT

 

设置请求体

请求体提供了五种类型:

  1. Form-data(表单)

  2. Json

  3. XML

  4. Raw(自定义文本类型数据)

  1. 设置 Query 参数

  1. Query 参数指的是地址栏中跟在问号?后面的参数,如以下地址中的 user_name 参数:

/user/login?user_name=jackliu

     2. 批量导入的数据格式为?key=value...,通过&分隔多个参数,如:

api.eolinker.com/user/login?user_name=jackliu&user_password=hello

     2. 设置 REST 参数

  1. REST 参数指的是地址栏被斜杠/分隔的参数,如以下地址中的使用大括号包裹起来的 user_name、user_password 参数:

/user/login/{user_name}/{user_password}

WARNING 注意,你只需要在 URL 中使用 {} 将 REST 参数括起来,表单的参数名不需要填写 {}。

API响应内容

设置响应头部

你可以输入或导入响应头部。批量导入的数据格式为 key : value ,一行一条 header 信息,如:

Connection: keep-aliveContent-Encoding: gzipContent-Type: application/jsonDate: Mon, 30 Dec 2019 20:49:45 GMT

设置响应内容

响应内容的编写方式和请求参数的类似,响应内容提供了四种类型:

  1. Json

  2. XML

  3. Raw(自定义文本类型数据)

以上这个工具叫 Eoapi(现更名 Poscat),是国产的开源 API 工具,除了最常用的文档和测试功能,

目前的 v 1.9.0 版本,新增团队协作、API 分享功能。除此之外他们还支持:

  • 强大的文档功能

  • 丰富的插件市场,可拓展

  • 前后置脚本

  • 支持查看所有测试历史

  • 支持 Websocket 协议,后续也会新增支持更多的主流协议

目前在 Github 上 3.5 k star,如果你觉得这个项目还不错的话,不妨点个 star 支持一下~

Github:

https://github.com/Postcatlab/postcat

Postcat 核心功能:

  • API 文档管理:可视化 API 设计,生成 API 文档

  • API 测试:自动生成测试参数,自动生成测试用例,可视化数据编辑

  • 插件拓展:众多插件扩展产品功能,打造属于你和团队的 API 开发平台

  • Mock:根据文档自动生成 Mock,或创建自定义 Mock 满足复杂场景

  • 团队协作:既能实现 API 分享也能可以创建云空间共同协作

Postcat 优势:

  • 免登录即可测试:省去繁琐的验证登录的操作

  • 界面简洁:没有冗余的功能与复杂选项

  • 免费:中小团队以及个人使用

  • 丰富的插件:支持数据迁移、主题、API 安全等高达 30 款插件

  • 国产:能更好的理解国内用户的需求,与开发团队沟通无障碍

  • 完善的用户文档:跟着操作就能快速上手


http://chatgpt.dhexx.cn/article/NpQDreym.shtml

相关文章

API调用,API传参,面向对接开发,你真的会写接口文档吗?

📢📢📢📢📢📢 💗 你正在阅读 【梦想橡皮擦】 的博客 👍 阅读完毕,可以点点小手赞一下 🌻 发现错误,直接评论区中指正吧 📆 橡皮擦的第…

接口接口文档

一、接口简介 API(Application Programming Interface)即应用程序接口,可以任务是一个软件组件或一个Web服务与外界进行交互的接口,在这里接口可以和API划等号。 接口可以简单的理解为一个黑盒子,从一边输入参数&…

【编程规范】 后端API接口设计编写与文档编写参考

文章目录 0 统一规范0.1 理清业务流程0.2 定义前后端开发的接口规范0.3 定义接口文档 1 后端接口编写1.0 后端接口介绍1.0.1 接口交互1.0.2 返回格式1.0.3 CODE状态码1.0.4 Message(Msg)1.0.5 DATA 1.1 数据校验与异常处理1.1.1 参数校验设计1.1.2 全局异…

如何根据接口文档,写一个接口类(举例说明)

直接先贴图(文中的url做了修改): 代码如下: FeignClient(name "Z_KPI_API",url "${Z.KPI.url:http://11.11.111.111:8080}",fallback ZApiClientFallback.class) public Interface ZApiClient{PostMappin…

Postman写接口文档

文章目录 参考首先了解什么是postman那么后端如何用postman编写接口文档,并且让前端或者其他开发人员也一起同步协作呢?1. 注册登录postman2. 创建项目工作区3. 编写接口文档4. 添加协作人(这一步也可以在创建工作区之初就操作)5.…

怎么写一份好的接口文档?

编写一份优秀的接口文档会让软件开发中变得更加轻松,更有效率。这可是关键任务,写得好不仅可以帮助开发人员更好地理解和使用 API 接口,还可以提高整个团队的协作效率。 大家可以在线感受一下优秀的接口文档是怎样的:https://pets…

接口文档的使用

请求参数((GET方法就是Query参数,POST方法就是 Body参数) 在 axios中通过headers选项设置Headers请求头参数 在 axios中通过data选项设置Body请求体参数 在 axios中通过params选项设置Query参数 如果有 Query 参数,axios 会在内部把这个对象…

接口文档包含哪些内容?怎么才能写好接口文档?十年测试老司机来告诉你

目录 接口文档结构 参数说明 示例 错误码说明 语言基调通俗易懂 及时更新与维护 总结 那么我们该如何写好一份优秀的接口文档呢? 接口文档结构 首先我们要知道文档结构是什么样子的。接口文档应该有清晰明确的结构,以便开发人员能快速定位自己需…

详解接口文档的编写

正规的团队合作或者是项目对接,接口文档是非常重要的,一般接口文档都是通过开发人员写的。一个工整的文档显得是非重要。下面我总结下自己看到的优秀接口文档。 一、背景介绍 接口:API API(Application Programming Interface&…

如何写好API接口文档

日常项目开发的过程中,接口文档是必不可少的。后端工程师与前端工程师之间需要接口文档来定义数据传输协议、系统对外暴露接口需要文档来说明、系统之间相互调用需要文档来记录接口协议等等。对于一个完整的项目,接口文档是至关重要的。那我们如何写好一…

什么是接口文档

一、什么是接口文档? 在项目开发中,web项目的前后端分离开发,APP开发,需要由前后端工程师共同定义接口,编写接口文档,之后大家都根据这个接口文档进行开发,到项目结束前都要一直维护。 二、为…

如何正确规范写接口文档

前言 正规的团队合作或者是项目对接,接口文档是非常重要的,一般接口文档都是通过开发人员写的。一个工整的文档显得是非重要。下面我将我看到的一篇接口文档做一个总结 开始吧!!! 接口1: 查询排重接口 接…

接口文档编写步骤与格式

接口文档编写步骤与格式 1. 基本步骤 梳理需求 依据业务写汉字版的接口文档。(可以减少在实际开发过程中的数据库调整) 写接口文档的过程中,会联想到需要上面样的数据。进而推出数据库设计。 数据库设计完毕。 正式的接口文档。 前端和后…

什么是接口文档,如何写接口,有什么规范?

一、什么是接口文档? 在项目开发中,web项目的前后端分离开发,APP开发,需要由前后端工程师共同定义接口,编写接口文档,之后大家都根据这个接口文档进行开发,到项目结束前都要一直维护。 二、为…

前后端接口文档编写

前后端分离需要编写接口文档,便于前后端工程师根据接口调用数据库和系统的功能。 接口分为四部分:方法、uri、请求参数、返回参数 1、方法:新增post、修改put、获取get、删除delete 2、uri:以"/"开头定义接口 3、请求参数和返回参…

怎么写接口文档

一些刚开始写接口文档的服务端同学,很容易按着代码的思路去编写接口文档,这让客户端同学或者是服务对接方技术人员经常吐槽,看不懂接口文档。这篇文章提供一个常规接口文档的编写方法,给大家参考。 推荐使用的是 http://docway.n…

圆环涂色问题

圆环涂色问题: 不考虑环形去序 本来我想的是第一个是m,后面是m-1,最后一个是m-2,但也可能倒数第二个和第一个是同色的,那么最后一个就可以是m-1了。所以全部取m-1,然后用上面的递推方法可以求得结果

关于环涂色问题的公式何其推导

问题描述:如下图,有M(m>2)个区域,如果给你n(n>3)种颜色,给这m个区域涂色, 要求相邻的区域颜色不能一样,问一共有几种涂法; 公式是:f(m)(-1)^m*(n-1)(n…

SCAU18730 涂色问题

思路:补集思想,快速幂 从正面想的话有点难度,从容斥定理的角度想了一会,发现重复的部分不会容斥。。。 我们从反面看,出现相邻相同数的方案总方案数-未出现相邻相同数的方案 总方案,每个位置有m种选择&a…

涂色问题

前言 一、处理策略 二、典例剖析 例1给一个各边不等的凸五边形的各边涂色,每边可以涂红、黄、蓝三种颜色中的一种,但是不允许相邻的边有相同的颜色,则不同的染色方法共有多少种? 分析:将凸五边形的各边依次编号为①②③…