apictl

apictl 是一个用于与 API 交互的命令行应用程序。请参阅下面的文档或运行 apictl help 获取详细信息。

安装

二进制文件可通过 发布 获得。

您也可以使用 cargo 安装它

cargo install apictl

入门

示例

此仓库包含一个示例 .apictl.yaml 文件。它与 Typicode 的 json-server 交互。您可以通过 npm 安装它，然后在其他 shell 中运行它

npm install -g json-server
json-server http://jsonplaceholder.typicode.com/db

现在您应该能够克隆此仓库并在其中运行示例

git clone https://github.com/icub3d/apictl
cd apictl
apictl requests list
apictl requests run -c local get-posts get-user-from-first-post
apictl requests run -c local new-post get-new-post

从头开始

如果您想使用现有的 API，请先为其创建一个 配置。配置通常位于创建 API 的仓库中。

接下来，为将要使用的各种环境创建 环境。

然后创建任何您感兴趣运行的 API 调用的 请求。

最后，在发布代码之前对您的配置进行一些测试。

配置

您可以通过查看 .apictl.yaml 来了解示例配置。配置使用 YAML 定义。默认情况下，apictl 将在当前目录中查找名为 .apictl.yaml 的文件。

如果您的项目足够大，您可以使用文件夹来存储多个配置文件。为此，请使用带有标志 --config CONFIG 运行 apictl，其中 CONFIG 是您的文件夹路径。文件夹将按顺序读取，并合并配置。当信息重叠（例如，具有相同名称的两个请求）时，后者将覆盖前者。

配置中值的详细信息请参阅下面。

环境

上下文是用于定义API调用变量的方法。在你的配置中，它们在contexts键下创建。每个上下文都是一个包含变量和替换值的映射。例如，假设你想区分本地、开发、预发布和产品环境中的请求URL。你可能这样做：

contexts:
  local:
    base_url: https://127.0.0.1:3000
  dev:
    base_url: https://dev.app
  staging:
    base_url: https://staging.app
  prod:
    base_url: https://my-cool-api.com

现在你可以在请求中使用变量base_url，它将被上下文提供的值替换。如果你想使用开发环境运行请求，你需要添加一个标志--context dev。

目前，如果变量是字符串，则会在请求中替换所有变量。如果正文包含字符串，则会被替换。文件引用的路径将被替换，但实际内容不会替换。

变量

一旦定义了上下文，你可以在配置中使用它们，使用模式${name}，其中name是上下文中的键。

多个上下文

你可以使用多个上下文，它们以类似配置的方式合并。当你有多个可能不重叠的交互时，这可能很有用。例如，你可能需要对同一API进行多个身份验证机制的测试。你可以使用一个上下文用于环境，然后用于身份验证方法。

要使用多个上下文，只需在命令中添加多个上下文标志：--context basic-auth --context local。

请求

请求是API端点和执行请求所需的信息。它们还包含基本信息，如tags和descriptions，可用于搜索请求。

在你的配置中，它们在requests键下创建。它们包含请求方法、URL、查询参数、头和正文的配置。除了正文之外，所有这些都是不言自明的。以下是一个示例请求：

requests:
  get-posts:
    tags: [get]
    description: a simple get
    url: "${base_url}/posts"
    query_parameters:
      _limit: "${pagination_limit}"

正文

请求正文可以有多种形式。本节将详细描述每种形式及其用法。每种正文类型都由type字段描述。

表单

如果你只想提交键/值对，可以使用“form”type，它将发送一个application/x-www-form-urlencoded。以下是一个示例：

requests:
  new-post:
    tags: [post]
    description: an example post using the form type
    url: "${base_url}/posts"
    method: POST
    body:
      type: form
      data:
        name: World
        age: 4.543 billion years

多部分表单

如果你要发送文件，你可能想使用多部分格式。它与表单类似，但允许你指定每个字段的类型。你使用“multipart”type，它将发送一个多部分消息。以下是一个示例：

requests:
  new-post:
    tags: [post]
    description: an example post using the multipart type
    url: "${base_url}/posts"
    method: POST
    body:
      type: multipart
      data:
        name:
          type: text
          data: World
        age:
          type: text
          data: 4.543 billion years
        avatar:
          type: file
          path: ./avatar.png

“file”type将期望在给定的path中有一个文件，并将它的内容放入表单提交中。

原始

如果你只想提交原始正文，请使用“raw”type。数据可以来自文本或文件，并将内容作为正文发送。以下是一个使用文本的示例

requests:
  new-post:
    tags: [post]
    description: an example post using the raw type
    url: "${base_url}/posts"
    method: POST
    body:
      type: raw
      from:
        type: text
        data: |
          {
            "userId": 1,
            "title": "test post",
            "body": "This is a test post to the json server."
          }

以下是一个使用文件的示例

requests:
  new-post:
    tags: [post]
    description: an example post using the raw type
    url: "${base_url}/posts"
    method: POST
    body:
      type: raw
      from:
        type: file
        path: ./new-post-body.json