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、纯文本等）。 |