常见问题

PostIn

PostIn - 文档

在接口开发中，团队常常面临接口频繁变更和文档维护困难的问题。主流工具如 Postman 和 Swagger 虽能部分解决这些问题，但仍存在局限性。推荐一款开源免费的 API 管理工具 - Postin ，提供 API 设计、调试、文档生成和 MOCK 数据模拟等一站式解决方案，有效简化了开发流程，提升团队协作效率。

Postin 提供了一系列功能，包括空间管理、接口调试、接口管理和分享管理等，帮助团队高效管理和调试 API 接口，提升协作效率。

空间是 Postin 中最高级别的项目管理单元，用于帮助团队高效地组织和管理 API 资源。它作为一个独立的容器，可以容纳项目的所有 API 接口、文档、测试等资源。

       帮助用户创建和管理不同的项目空间，方便团队根据项目需求组织 API 接口、文档及相关资源，确保项目资源的高效分类和管理。

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

       提供对可复用数据模型的定义和管理，支持在多个 API 设计和调试过程中使用，确保数据的一致性和准确性。

       提供项目进展和接口使用情况的跟踪，便于数据分析和优化决策。

       便于项目成员的角色和权限分配，确保高效协作。

       自定义项目权限设置，控制成员的操作权限，保障项目安全。

Postin 提供全面的接口管理功能，包括设计、调试、文档生成和Mock等功能，支持 HTTP 和 WebSocket 协议，帮助开发者高效管理和测试 API 接口。

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

WebSocket协议：WebSocket 协议设计涵盖了基础信息、请求参数的设计

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

接口调试功能，基于接口设计自动生成数据，支持 HTTP 和 WebSocket 协议，帮助开发者快速验证和调试 API 接口

Postin 提供内置的 HTTP 协议 MOCK 数据生成功能，支持前端在后端未完成时进行独立开发和测试，减少依赖，提升开发效率。

Postin 提供快速便捷的接口调试功能，与接口管理中的接口区别在于需要手动输入参数，用于临时测试不需要管理的接口。支持 HTTP 和 WebSocket 协议，帮助开发者验证 API 接口的功能和行为，确保接口按预期工作。

用于管理分享后的接口文档，方便团队成员和外部开发者快速获取所需信息，促进协作。

Postin 的优势包括简洁的界面，私有部署一键安装，开源免费，支持多版本和多终端使用，保障数据安全和可靠性，具备强大的系统集成功能，满足不同开发团队的需求

界面简洁，上手简单，支持一键式安装配置。

       直观的界面设计，结构清晰，让用户可以快速找到所需的功能模块。

      私有部署支持一键安装，安装后即刻可用，无需额外配置。

提供多层级权限控制、日志审计和备份与恢复功能，确保数据安全和操作透明，防止未经授权的访问和数据丢失。

      通过应用级、系统级和项目级权限管理，确保不同角色和成员在不同层次上获得恰当的访问权限，从而保障项目的安全性。

      实时记录所有操作变动，便于追溯到具体用户和时间，确保操作透明。

      定期备份数据，实时恢复，防止数据误删或损坏。

支持导入Postman、Swagger 和 OpenAPI 接口文档，实现与主流工具的无缝集成，简化接口管理流程。

集成到 TikLab 全家桶生态中的 TestHubo 产品，实现测试与接口管理的无缝协作。

支持不同版本的部署，可在多个平台和设备上使用，确保灵活性和兼容性，满足多样化的开发需求。

免费开放源代码，支持社区协作和共享，推动项目不断发展和优化。

了解更多关于 Postin 的信息，请访问以下链接：

关于PostIn

PostIn社区版需要升级企业版，首先先需要确定当前版本，在PostIn

，可以找到当前的版本类型，点击“企业版特性”可以浏览到社区版和企业版功能对比。

如需要升级企业版，点击右侧订阅按钮。

点击订阅按钮，页面打开官网，用户需要经过登录后，进入订阅管理，选PostIn点击订阅。

在订阅页面输入需要购买的时长和购买数量（即需要使用系统的用户数量），确认无误后，点击前往支付。

其中根据购买时长、购买数量价格上会有不同优惠。

支付完成后，在已订阅会显示订阅的产品，点击订阅的产品右侧的“licence”。

在弹出的窗口填入PostIn服务器的MAC地址，即可升级企业版。

订阅成功后，在订阅管理可以查看已购产品订阅的版本、订阅人数、订阅有效期，已订阅的产品进行续订和扩容。

社区版与企业版的区别

加入我们的技术交流群，参与互动交流，提升自我

联系我们

产品介绍

PostIn支持用户自定义端口、数据库、统一登录等配置，用户可以根据自己的需求来更改，只需要编辑默认文件

application.yaml即可。PostIn的配置文件位置：默认在/opt/tiklab-postin/conf 目录下。

允许用户自定义应用的启动端口，以便在特定网络环境下避免端口冲突或满足其他配置需求。

支持用户自定义数据存放目录的位置，帮助用户根据需要选择存储路径。

支持自定义数据库连接方式，用户可以选择使用内嵌数据库或指定外部数据库地址。根据需求配置数据库连接。

的用户，部门等，这样配置可以让一个用户同时使用多个应用。需要安装Soular，具体安装详见

程序安装结束后，可以在系统执行如下。

使用 postin -v 或者 postin version 查看当前安装版本。

Linux 安装配置

启动完成后，这样你就可以通过 http://localhost:9300 访问 PostIn 界面了，初始化账号为：admin ,密码为：123456，首次登录需要更改密码。

支持用户使用脚本一键升级，只需要执行应用升级脚本即可。

Docker 安装配置

允许自定义端口、数据存放目录、数据库连接、数据库备份策略和统一登录设置，以满足特定个性化需求。yaml文件默认位置：

Windows 安装配置

允许自定义端口、数据存放目录、数据库连接、数据库备份策略和统一登录设置，以满足特定个性化需求。yaml文件默认位置：默认在app下的Contents --> conf目录下

更新完成Contents下会出现backups文件夹，里面存放的是之前的数据文件。

MacOS 安装配置

安装配置

PostIn安装结束并登录后，需要创建空间来对接口分项目进行管理，空间是 Postin 中最高级别的项目管理单元，用于帮助团队高效地组织和管理 API 资源。它作为一个独立的容器，可以容纳项目的所有 API 接口、文档、测试等资源。

通过创建空间可以帮助开发团队有效地集中管理项目相关的接口资源，使得团队成员能够快速查找和使用所需的 API 信息。点击

，可添加公共或者私密的空间，其中公共空间所有用户可浏览，私密空间仅选择的用户可浏览。

在空间页面，点击右上角“添加空间”按钮，弹出添加空间页面。

空间创建完成之后，在空间页面“所有空间”，或者“我创建的”找到创建的空间。点击空间名称，进入空间详情。

空间创建成功之后，根据空间的属性对访问空间的成员进行管理。

在项目页面找到空间，点击“空间成员”，对访问空间的成员进行管理。

添加空间成员之前，需要添加系统用户，依次点击

，展示用户列表。系统内置管理员用户，无法删除。

点击“添加用户”，展现添加用户弹窗。

添加账号成功之后，可以对账号进行编辑、修改密码、重置密码、删除。

系统用户添加完成之后，可以对空间成员进行添加，在

如果用户在创建空间未选成员，那么空间默认有创建人和admin两个成员。点击添加用户，添加的成员列表从系统用户列表获取。

勾选添加用户，点击确定即可成功添加空间成员。

添加空间成员后，对成员修改角色，点击

，点击“角色修改”，对成员角色进行修改。成员角色可多选。

创建成功之后，默认进入该空间的空间详情，在空间详情，对空间下所有接口进行管理。

空间详情——概况，展示空间各个状态接口的数量、空间的最近动态。

空间详情——接口调试，不记录接口信息，对接口进行简单调试。

空间详情——接口，将接口记录到空间中，生成接口文档，选择环境对接口进行调试。

空间详情——分享，在接口页面可以对保存下来的接口文档进行分享，空间外的成员（外部人员）可以通过打开分享的链接浏览接口文档。在分享页面可以看到分享过的接口，对分享过的接口进行管理。

创建空间

WebSocket协议在接口调试页面区别。

‌HTTP协议客户端发起请求后，服务器返回响应即断开连接，每次通信需重新建立连接。在接口调试页面选择HTTP协议，界面显示HTTP协议接口调试需要的项目。

接口调试页面，点击tabs页右侧的“+”号，添加一个新的接口调试tabs。

选择“HTTP”协议，显示请求方式下拉框，输入需要测试接口的请求方式，支持的请求方式包含GET、POST、HEAD、PUT、DELETE、PATCH。

在地址栏中输入需要测试的接口地址，包括主机和路径等信息。

在相应的输入框或表单中输入需要传递给接口的请求参数。这些参数可以包括查询参数、请求体参数、请求头等，根据接口的需求进行输入。

点击界面上的发送按钮，将测试请求发送给目标接口。系统将会使用输入的请求地址和参数发送请求，并等待接收到服务器的响应。

在接收到服务器的响应后，系统会将响应结果显示在界面上，包括响应状态码、响应体内容等信息。用户可以在界面上直接查看测试结果，以便进行验证和调试。

WebSocket‌协议连接建立后客户端与服务器可双向实时传输数据，无需重复握手。在接口调试页面选择WebSocket协议，界面显示WebSocket协议接口调试需要的项目。

要与服务器进行通信，你首先需要建立一个 WebSocket 连接。只需点击“连接”按钮即可。

在请求栏输入需要传递给接口的请求参数。这些参数可以包括查询参数、请求体参数、请求头。

在接收到服务器的响应后，系统会将响应报文显示在界面上。用户可以在界面上直接查看测试结果，以便进行验证和调试。

在接口请求发送‌之前‌执行，主要用于准备测试数据、动态修改请求参数或设置环境变量。

例如，使用前置脚本设置请求头参数ticket。

或者还可以设置一些其他前置脚本。例如生成随机用户ID和当前日期，并将生成的数据写入请求体表单中 。

在接口请求发送‌之后‌执行，主要用于解析响应数据、断言校验、清理测试数据或传递参数给后续请求。

例如登录接口，取响应体json中data.ticket，将动态值存储至环境变量ticket中，后续通过{{ticket}}引用。

‌支持可视化断言，在接口调试点击断言，显示需要输入断言的来源（状态码、响应体、响应头）、属性名称、比较符、参数值。添加完成之后，调试接口在接口响应栏下断言tab，显示断言是否成功。

包括验证响应体中是否‌包含特定字符串‌‌、‌JSON字段值是否匹配预期‌‌，或直接对比整个响应体与预设字符串是否完全一致‌。

例如，如上图的断言显示执行成功。

接口每一次调试都会记录在左侧接口调试历史列表，点击调试历史列表，右侧显示调试时设置的参数。

点击调试历史右侧的删除按钮，可以对调试历史进行删除。点击接口调试列表右上角“扫把”按钮，清空调试历史列表。

接口调试

点击右侧导航栏的“接口”进入接口页面，接口以目录的形式进行分组。添加接口之前需要先添加目录，点击列表右上角的“+”，添加接口目录。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

选择环境之后，点击“发送”，对接口进行测试。

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

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

接口管理

在接口点击Mock，进入Mock页面，显示内置Mock环境地址。

点击页面右上角“添加MOCK”，添加MOCK。

添加MOCK后，MOCK默认为启用状态，可以在MOCK列表对MOCK进行启用\禁用。

点击添加MOCK，输入MOCK的名称后，点击提交，添加一条MOCK虚拟响应。

配置MOCK虚拟请求后，使用MOCK环境，点击测试，如果请求和MOCK一致，则接口响应也会和MOCK设置的一致。

，选择MOCK环境，当请求参数符合

MOCK“查询成功”的请求参数，则显示响应code:200，响应体：{"msg": "查询成功"}

MOCK“查询失败”的请求参数，则显示响应code:201，响应体：{"msg": "请输入日期进行查询"}

MOCK默认为启用状态，使用MOCK环境，当请求参数符合MOCK设置的请求参数，接口会根据MOCK设置给出响应。

此时禁用MOCK，再次使用符合MOCK设置的请求参数，此时接口返回失败。

点击MOCK右侧的编辑按钮，可对MOCK的基本信息进行编辑。

 点击MOCK右侧的删除按钮，可删除对应MOCK。注意：删除的MOCK无法恢复，请谨慎操作。

MOCK虚拟数据

快速入门

页面展示常用空间、所有空间接口统计。

常用空间相当于最近访问的空间。在进入主页时，点击常用空间的显示卡片快速进入空间。常用空间卡片显示空间logo、空间名称、空间目录数、空间接口数信息。

显示所有空间设计中、开发中、测试、异常状态的接口数量。

接口趋势统计显示最近8天（不显示当天）接口数量趋势折线图，将光标移动到折线图上，显示当条数据的数据标签。

接口状态统计显示当天时间点系统内所有状态接口数量

首页

查询空间

编辑空间

删除空间

概况

空间信息

环境设置

模型

成员

权限

空间设置

空间

HTTP测试

WebSocket测试

查询目录

创建目录

查看目录

编辑目录

删除目录

查询接口

创建接口

删除接口

HTTP

Websocket

查看接口

用户与权限

消息

插件

安全

应用

系统设置

postin-doclet

高级功能

使用指南

最佳实践

V1.0.5更新日志

针对 IntelliJ IDEA 环境推出 PostIn 插件，版本号1.0.1， PostIn 插件是一个针对 IntelliJ IDEA 环境的工具，集成到 IDEA 侧面板中，便于快速访问，帮助开发人员高效地管理API定义。插件可自动生成 API 文档并一键同步到 PostIn 的项目中。

➢ 优化 IntelliJ IDEA 环境 PostIn 插件功能显示。