README

Drafter API Blueprint 解析器的PHP包装器。

什么是 Drafter-php？

Drafter-php 允许您在PHP应用程序中使用drafter API Blueprint解析器。

简单来说：您可以转换API Blueprint文件为解析结果。

API Blueprint是一个基于Markdown的webservice文档语言。

要求

PHP 8.0 或更高版本
Drafter 命令行工具

什么是什么是

Drafter 是一个用于解析API Blueprint的C++工具。
Drafter-php 是围绕 Drafter命令行工具 的PHP包装器。

安装

推荐使用 composer 安装 Drafter-php。

$ composer require hmaus/drafter-php

这将安装应用程序的PHP包。
请注意，Drafter不包括在内。

使用Composer安装Drafter命令行工具

前往 hmaus/drafter-installer。

Drafter-php的用法

获取 \DrafterPhp\DrafterInterface 实现的实例，\DrafterPhp\Drafter 1.1 您需要将drafter二进制文件的路径传递给构造函数 1.2 建议使用依赖注入容器解决这个问题
在您的 \DrafterPhp\Drafter 实例上设置输入文件和选项 2.1 Drafter-php目前不支持直接将blueprint代码传递给Drafter；此时必须存储在文件中
运行您的命令

输入/输出示例

注意：drafter-php不会断言输出的结构。如果您在示例与实际输出中看到差异，请参阅官方drafter文档。

给定此api blueprint源

# GET /message
+ Response 200 (text/plain)

        Hello World!

结果将类似（json refract）

{
  "element": "parseResult",
  "content": [
    {
      "element": "category",
      "meta": {
        "classes": [
          "api"
        ],
        "title": ""
      },
      "content": [
        {
          "element": "category",
          "meta": {
            "classes": [
              "resourceGroup"
            ],
            "title": ""
          },
          "content": [
            {
              "element": "resource",
              "meta": {
                "title": ""
              },
              "attributes": {
                "href": "/message"
              },
              "content": [
                {
                  "element": "transition",
                  "meta": {
                    "title": ""
                  },
                  "content": [
                    {
                      "element": "httpTransaction",
                      "content": [
                        {
                          "element": "httpRequest",
                          "attributes": {
                            "method": "GET"
                          },
                          "content": []
                        },
                        {
                          "element": "httpResponse",
                          "attributes": {
                            "statusCode": "200",
                            "headers": {
                              "element": "httpHeaders",
                              "content": [
                                {
                                  "element": "member",
                                  "content": {
                                    "key": {
                                      "element": "string",
                                      "content": "Content-Type"
                                    },
                                    "value": {
                                      "element": "string",
                                      "content": "text/plain"
                                    }
                                  }
                                }
                              ]
                            }
                          },
                          "content": [
                            {
                              "element": "asset",
                              "meta": {
                                "classes": [
                                  "messageBody"
                                ]
                              },
                              "attributes": {
                                "contentType": "text/plain"
                              },
                              "content": "Hello World!\n"
                            }
                          ]
                        }
                      ]
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

代码示例

发现错误？请随时贡献

确保它正常工作

为了确保它正常工作，我们将要求Drafter提供当前版本。

$version = $drafter
    ->version()
    ->run();

// Reset options on the command
$drafter->resetOptions();

$version 现在应包含类似于 v1.0.0 的字符串。如果出现问题，最有可能抛出异常。

请注意，Drafter-php旨在保持其状态，运行 \DrafterPhp\DrafterInterface::resetOptions 以删除您刚刚设置的版本选项，以便在实例的下一个调用中。

将your-service.apib解析为your-service.refract.json

确保您的输入路径正确且可读，并且您的输出路径可写。

$drafter
    ->input('your-service.apib')
    ->format('json')
    ->type('refract')
    ->output('your-service.refract.json')
    ->run();

将your-service.apib解析为your-service.ast.json

确保您的输入路径正确且可读，并且您的输出路径可写。

$drafter
    ->input('your-service.apib')
    ->format('json')
    ->output('your-service.ast.json')
    ->run();

将your-service.apib解析为PHP数据结构

$refract = $drafter
    ->input('your-service.apib')
    ->format('json')
    ->run();
    
$phpObj = json_decode($refract);
$phpArr = json_decode($refract, true);

将your-service.apib解析为YAML格式

$drafter
    ->input('your-service.apib')
    ->format('yaml') // optional as yaml is the default
    ->output('your-service.ast.yml')
    ->run();

获取在运行之前的进程

$process = $drafter
    ->input('your-service.apib')
    ->format('json')
    ->output('your-service.refract.json')
    ->build();

// do stuff with the process

$drafter
    ->run($process);

功能路线图

不要犹豫，贡献力量。

支持将原始API蓝图代码传递给 \DrafterPhp\DrafterInterface::input，而不是总是文件路径

许可证

Drafter-php采用MIT许可证授权 - 请参阅LICENSE文件以获取详细信息

goez / drafter-php

维护者

详细信息