README

将 API Blueprint JSON文件转换为 Postman 集合。

以Phar形式安装Blueman（推荐）

使用安装程序下载Blueman

$ curl -sS http://blueman.pixelfusion.co.nz/installer.php | php

这将获取Blueman的最新版本并将其复制到您的当前目录。我们建议将其移动到bin目录，以便您可以从任何位置运行Blueman

$ mv blueman.phar /usr/local/bin/blueman

每当有Blueman的新版本时，您可以运行 self-update 来更新到最新版本

$ blueman self-update

使用Composer安装

如果您愿意，也可以使用Composer安装Blueman

$ composer create-project pixelfusion/blueman your-project-name

先决条件

您想使用Blueman转换的API Blueprint JSON文件应使用 Drafter 创建。默认情况下，Drafter创建 refract 格式的JSON文件，但Blueman仅支持 AST 格式。您必须通过传递 -t 参数强制Drafter使用 AST，例如

drafter -f json -t ast -o api.json api.md

注意：截至2015年12月，API Blueprint AST格式已被弃用。API Blueprint AST已被 API描述Refract命名空间 取代。在此阶段，Blueman仅支持 AST 格式，因此一旦Drafter停止生成 AST 格式的文件，Blueman 将不再工作。非常感谢为添加对 refract 格式的支持而提交的Pull Requests！

使用方法

要生成Postman集合，请运行 convert 命令。例如，如果您生成的API Blueprint JSON文件名为 api.json，您将执行以下命令

$ blueman convert api.json

注意：如果您使用Composer安装了Blueman，则必须在所有示例命令中将 blueman 替换为 ./bin/console，例如

$ ./bin/console convert api.json

此命令将生成一个名为 collection.json 的文件，您可以在Postman中导入此文件。

默认情况下，Blueman将在您运行命令的位置寻找JSON文件。如果您的文件在其他目录中，您需要指定路径

$ blueman convert api.json --path=/Users/wouter/Desktop

指定输出文件

默认情况下，Blueman将在当前目录中创建一个名为 collection.json 的文件。您可以将文件保存到不同的文件夹，并通过传递输出参数更改输出文件名

$ blueman convert api.json --output=/Users/wouter/Desktop/postman_collection.json

设置主机

您API的基础主机可以通过几种不同的方式设置。

首先，您可以通过将以下行添加到您的API Blueprint Markdown文件的顶部作为元数据来指定它

HOST: https://api.example.com/v1

如果您的Markdown文件没有主机元数据或您想覆盖它，您可以在执行 convert 命令时指定主机

$ blueman convert api.json --host=https://api.example.com/v1

最后，如果您没有做以上任何一项，则在您执行 convert 命令时将被提示设置主机。

提示：如果您使用Postman中的环境在不同的服务器上测试API（沙盒、用户验收测试等），您可以使用主机选项指定您在Postman环境配置中设置的占位符密钥

$ blueman convert api.json --host=https://api.{{host}}/v1

Postman测试

Blueman还允许您定义Postman测试。

要使用此功能，您需要在api.json文件所在的路径下创建一个Markdown文件（参见 --path 选项）。默认情况下，Blueman 会尝试读取名为 blueman.tests.md 的文件。查看test/api.test.md 文件以获取语法示例。如果您想使用不同的名称，可以在运行 convert 命令时指定 --test-filename 参数。

使用示例

$ blueman convert api.json --include-tests 

如果您的测试文件名不是 blueman.tests.md，则需要指定文件名

$ blueman convert api.json --include-tests --tests-filename=<YOUR_FILNAME>.md