PostIn零基础学习 - 如何快速设计并分享接口文档

PostIn是一款国产开源免费的接口管理工具，包含项目管理、接口调试、接口文档设计、MOCK数据、测试用例、测试计划等模块，支持免登陆本地接口调试。本文将介绍如何快速设计接口并分享接口文档。

1、添加接口

项目、成员创建成功之后，进入项目详情，显示接口管理页面，接口以目录的形式进行分组。添加接口之前需要先添加目录，点击列表右上角的“+”，添加接口目录。

添加目录

目录名称必填，目录添加完成之后，可以在目录下添加接口，或者添加子目录。

1.1 HTTP接口

在目录右侧点击“+”添加接口，包含添加HTTP或者WebSocket协议接口。选择添加HTTP，输入接口的基本信息接口名称、请求类型、接口路径，点击“提交”，成功添加接口。

添加HTTP接口

属性	是否必填	描述
接口名称	必填	为接口设置名称，简单描述一下接口目的，方便后期识别管理。
请求方式	必填	HTTP接口请求方式，支持GET、POST、HEAD、PUT、DELETE、PATCH。
接口路径	必填	具体接口在服务器上的位置。
描述	选填	提供接口简短描述，方便后期团队成员快速了解接口。

1.2 WebSocket接口

在目录右侧点击“+”，选择添加WebSocket协议接口，输入接口的基本信息接口名称、请求类型、接口路径，点击“提交”，成功添加接口。

添加WebSocket接口

属性	是否必填	描述
接口名称	必填	为接口设置名称，简单描述一下接口目的，方便后期识别管理。
接口路径	必填	具体接口在服务器上的位置。
描述	选填	提供接口简短描述，方便后期团队成员快速了解接口。

在接口列表，可以对接口名称进行模糊查询。

接口查询

也点击目录的接口右侧“…”，对接口进行编辑、删除。

编辑、删除接口

2、导入接口

除了手动添加接口这个方式，PostIn还支持通过Postman/OpenAPI V3/Swagger V2的json格式导入。在目录右侧点击“+”，选择导入。

导入接口

选择导入json的类型，上传json文件。上传json文件的时候会校验相关格式。

不符合格式提醒

上传符合格式的json文件，点击提交，成功导入接口。

3、设计接口

接口设计通过设置基础信息、请求和输出结果的参数，来构造当前接口的具体使用方式。支持多种协议，包括 HTTP协议和 WebSocket协议，灵活适应不同应用需求。

• HTTP 协议：设计涵盖了基础信息、请求参数和响应结果的设计。
• WebSocket 协议：设计涵盖了基础信息、请求参数的设计。

接口设计

请求参数：

属性	描述
Header	位于HTTP请求的头部，用于传递元数据。
Query	出现在URL问号后，对资源进行筛选、排序或分页。
Path	嵌入在URL路径中，明确标识资源的唯一路径。
Body	位于HTTP请求的正文，用于传递实际数据。

其中Body类型及其用途如下。

属性	描述
none	不设置请求Body。
form-data	上传文件或同时提交文本和文件。
x-www-form-urlencoded	提交简单的键值对表单数据，适用于传统 HTML 表单提交。
json	Raw 的子集，严格遵循JSON语法（键值对、双引号、嵌套结构等），用于结构化数据传输。
raw	原始数据格式，支持任意文本内容（如JSON、XML、纯文本等）。

4、测试接口

4.1 设置环境

Postin 测试调试接口支持管理多个环境配置（如开发、测试、生产），便于在不同环境中测试和验证 API。

在测试API接口之前，点击基础数据→设置→环境，进入环境配置。

环境配置

点击添加环境，需要输入环境名称、环境地址。注意：环境地址尾部不需要带“/”

属性	是否必填	描述
环境名称	必填	为环境设置一个简洁明了的名称，便于识别和管理。
环境地址	必填	接口请求的目标地址，与接口路径组成接口请求的完整地址。

在环境页面，可以对环境可以进行编辑、删除。

环境配置结束后，在接口测试页面，点击右上角环境下拉框，选择测试接口所用的环境。

选择测试环境

4.2 测试接口

环境设置结束后，在测试页面，点击环境下拉框，弹出环境选择，点击需要测试的环境，点击发送，进行接口测试。

接口测试

5、查看接口文档

接口文档基于接口设计自动生成，确保接口信息实时更新，便于团队随时查阅和对接，支持 HTTP 和 WebSocket 协议，方便共享给其他开发者或团队成员。

接口文档

6、分享接口

在接口页面选择需要分享的接口，点击右上角分享按钮。

接口分享

接口分享支持公开分享和密码分享两种方式。

• 公开分享：在浏览器中打开分享界面的链接，直接可以打开分享的接口。
• 密码查看：打开分享的链接咋需要输入密码后才支持浏览接口。支持自定义密码分享（密码区分大小写）。

分开分享接口

打开分享窗口后，复制分享链接，其他用户可通过分享的链接查看接口。

查看接口

支持查看分享的接口，点击左侧“分享”按钮，在分享页面显示分享过的接口列表。在分享页面，可以查看接口分享的链接、修改分享密码、取消分享。

分享管理

有兴趣的朋友欢迎前往tiklab官网体验在线版本、或者免费下载私有化部署体验。