From c4dbf8dc33a8cfc72238b4522d06c4f2d99fe38b Mon Sep 17 00:00:00 2001 From: Sean Molenaar Date: Tue, 23 Aug 2016 09:43:55 +0200 Subject: [PATCH 1/2] Adding cURL command generation --- src/PHPDraft/HTML/default.php | 1 + src/PHPDraft/Model/HTTPRequest.php | 1 - 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/src/PHPDraft/HTML/default.php b/src/PHPDraft/HTML/default.php index fb3cdcee..348a58f4 100644 --- a/src/PHPDraft/HTML/default.php +++ b/src/PHPDraft/HTML/default.php @@ -127,6 +127,7 @@ class="panel panel-default get_method(); ?>"> base_data['HOST']; ?> build_url(); ?> + get_curl_command($this->base_data['HOST']); ?> diff --git a/src/PHPDraft/Model/HTTPRequest.php b/src/PHPDraft/Model/HTTPRequest.php index 8bc4b759..cc42697a 100644 --- a/src/PHPDraft/Model/HTTPRequest.php +++ b/src/PHPDraft/Model/HTTPRequest.php @@ -37,7 +37,6 @@ class HTTPRequest public function __construct(&$parent) { $this->parent = &$parent; - //TODO: Parse body } public function parse($object) From fbfd9404f1c02239b359cbc9bbb71d26f1b21cdc Mon Sep 17 00:00:00 2001 From: Sean Molenaar Date: Tue, 23 Aug 2016 18:10:30 +0200 Subject: [PATCH 2/2] Code cleanup --- .gitignore | 1 + README.md | 23 ++++++++---- config.json | 3 +- config.json.sample | 4 +++ index.php | 16 ++++++++- src/PHPDraft/In/ApibFileParser.php | 16 ++++++--- src/PHPDraft/Model/APIBlueprintElement.php | 2 +- src/PHPDraft/Model/Category.php | 22 +++--------- src/PHPDraft/Model/DataStructureElement.php | 9 +++-- .../{ => Elements}/RequestBodyElement.php | 10 +++++- src/PHPDraft/Model/HTTPRequest.php | 30 ++++++++++++++-- src/PHPDraft/Model/HTTPResponse.php | 9 ++++- src/PHPDraft/Model/Resource.php | 11 ++++-- .../Model/Tests/DataStructureElementTest.php | 11 +++++- src/PHPDraft/Model/Transition.php | 30 ++++++++++++++-- src/PHPDraft/{ => Out}/HTML/default.php | 0 src/PHPDraft/{ => Out}/HTML/index.css | 0 src/PHPDraft/Out/TemplateGenerator.php | 35 +++++++++++++------ src/PHPDraft/Parse/ApibToJson.php | 11 +++--- src/PHPDraft/Parse/JsonToHTML.php | 7 ++++ src/PHPDraft/Parse/Tests/ApibToJsonTest.php | 19 ++++++++++ src/PHPDraft/Parse/Tests/JsonToHTMLTest.php | 12 +++++++ tests/phpunit.xml | 8 +++-- tests/test.bootstrap.inc.php | 2 +- 24 files changed, 231 insertions(+), 60 deletions(-) create mode 100644 config.json.sample rename src/PHPDraft/Model/{ => Elements}/RequestBodyElement.php (93%) rename src/PHPDraft/{ => Out}/HTML/default.php (100%) rename src/PHPDraft/{ => Out}/HTML/index.css (100%) diff --git a/.gitignore b/.gitignore index 7517b3f2..6d23f618 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,4 @@ # JIRA plugin atlassian-ide-plugin.xml +config.json \ No newline at end of file diff --git a/README.md b/README.md index 0991f40f..679a817e 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,29 @@ -# PHP-Drafter +# PHPDraft This is a parser for API Blueprint files in PHP. ## Usage For direct usage you can run: ```bash -$ ./php-drafter.phar blueprint-file.apib > blueprint-webpage.html +$ ./phpdraft.phar blueprint-file.apib > blueprint-webpage.html ``` You can also install it first: ```bash -$ cp php-drafter.phar /usr/bin/php-drafter -$ chmod +x /usr/bin/php-drafter -$ php-drafter blueprint-file.apib > blueprint-webpage.html +$ cp phpdraft.phar /usr/bin/phpdraft +$ chmod +x /usr/bin/phpdraft +$ phpdraft blueprint-file.apib > blueprint-webpage.html ``` +## Including Files +It is possible to include other files in your blueprint by using a special include directive with a path to the included file relative to the current file's directory. Included files can be written in API Blueprint, Markdown or HTML (or JSON for response examples). Included files can include other files, so be careful of circular references. + +```markdown + +``` + +For tools that do not support this include directive it will just render out as an HTML comment. API Blueprint may support its own mechanism of including files in the future, and this syntax was chosen to not interfere with the [external documents proposal](https://github.com/apiaryio/api-blueprint/issues/20) while allowing `PHPDraft` users to include documents today. + +_Thanks to [aglio](https://github.com/danielgtaylor/aglio) for the idea._ + ## Writing API documentation For writing API documentation using [API Blueprint](http://apiblueprint.org/) syntax. You can read about its [specification](https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md). @@ -65,7 +76,7 @@ Return the information for the Person ## Dependencies -PHP-Drafter requires [drafter](https://github.com/apiaryio/drafter) to be installed. Refer to the drafter page for the installation details. +PHPDraft requires [drafter](https://github.com/apiaryio/drafter) to be installed. Refer to the drafter page for the installation details. ## Libraries This app usage the following libraries: diff --git a/config.json b/config.json index 9bbb189e..cca2df80 100644 --- a/config.json +++ b/config.json @@ -1,3 +1,4 @@ { - "tmpdir": "/tmp/drafter" + "tmpdir": "/tmp/drafter", + "logo": "/home/smillernl/Documents/5acf473a9e6a3deb8e98a2b6373d0a83.png" } \ No newline at end of file diff --git a/config.json.sample b/config.json.sample new file mode 100644 index 00000000..bf8478ce --- /dev/null +++ b/config.json.sample @@ -0,0 +1,4 @@ +{ + "tmpdir": "/tmp/drafter", + "logo": "/path/to/some/logo.png" +} \ No newline at end of file diff --git a/index.php b/index.php index 93faa05d..87b73ef4 100755 --- a/index.php +++ b/index.php @@ -1,13 +1,27 @@ parseToJson(); $html = new JsonToHTML($json); -echo $html->get_html(); +$html->get_html(); ?> diff --git a/src/PHPDraft/In/ApibFileParser.php b/src/PHPDraft/In/ApibFileParser.php index b264c816..bf143c43 100644 --- a/src/PHPDraft/In/ApibFileParser.php +++ b/src/PHPDraft/In/ApibFileParser.php @@ -10,8 +10,16 @@ class ApibFileParser { - protected $out_string; + /** + * Complete API Blueprint + * @var string + */ + protected $full_apib; + /** + * Location of the API Blueprint to parse + * @var string + */ protected $location; /** @@ -21,8 +29,8 @@ class ApibFileParser */ public function __construct($filename = 'index.apib') { - $this->location = pathinfo($filename, PATHINFO_DIRNAME) . '/'; - $this->out_string = $this->get_apib($filename); + $this->location = pathinfo($filename, PATHINFO_DIRNAME) . '/'; + $this->full_apib = $this->get_apib($filename); } /** @@ -52,7 +60,7 @@ function get_apib($filename) */ function __toString() { - return $this->out_string; + return $this->full_apib; } } \ No newline at end of file diff --git a/src/PHPDraft/Model/APIBlueprintElement.php b/src/PHPDraft/Model/APIBlueprintElement.php index 500db4fa..b6b1aec8 100644 --- a/src/PHPDraft/Model/APIBlueprintElement.php +++ b/src/PHPDraft/Model/APIBlueprintElement.php @@ -41,7 +41,7 @@ abstract class APIBlueprintElement protected $parent = NULL; /** - * Parse an object to an element + * Parse a JSON object to an element * * @param \stdClass $object an object to parse * diff --git a/src/PHPDraft/Model/Category.php b/src/PHPDraft/Model/Category.php index de7021ea..463760aa 100644 --- a/src/PHPDraft/Model/Category.php +++ b/src/PHPDraft/Model/Category.php @@ -2,7 +2,7 @@ /** * This file contains the Category.php * - * @package php-drafter\SOMETHING + * @package PHPDraft\Model * @author Sean Molenaar */ @@ -17,25 +17,11 @@ class Category extends APIBlueprintElement public $structures = []; /** - * Add a struct dependency + * Fill class values based on JSON object * - * @param string $object Name of the struct to add + * @param \stdClass $object JSON object * - * @internal param string $name Name of the type - */ - public function add_struct($object) - { - echo "
";
-        var_dump($object);
-        echo "
"; - } - - /** - * Parse the category - * - * @param \stdClass $object - * - * @return $this + * @return $this self-reference */ function parse($object) { diff --git a/src/PHPDraft/Model/DataStructureElement.php b/src/PHPDraft/Model/DataStructureElement.php index 6a6cc765..34fad102 100644 --- a/src/PHPDraft/Model/DataStructureElement.php +++ b/src/PHPDraft/Model/DataStructureElement.php @@ -2,7 +2,7 @@ /** * This file contains the DataStructureElement.php * - * @package php-drafter\SOMETHING + * @package PHPDraft\Model * @author Sean Molenaar */ @@ -15,26 +15,31 @@ class DataStructureElement * @var string */ public $key; + /** * Object JSON type * @var string */ public $type; + /** * Object description * @var string */ public $description; + /** * Type of element * @var string */ public $element = NULL; + /** * Object value * @var mixed|DataStructureElement[] */ public $value = NULL; + /** * Object status (required|optional) * @var string @@ -48,7 +53,7 @@ class DataStructureElement public $deps; /** - * Unreported datatypes + * Default datatypes * @var array */ protected $defaults = ['boolean', 'string', 'number', 'object', 'array']; diff --git a/src/PHPDraft/Model/RequestBodyElement.php b/src/PHPDraft/Model/Elements/RequestBodyElement.php similarity index 93% rename from src/PHPDraft/Model/RequestBodyElement.php rename to src/PHPDraft/Model/Elements/RequestBodyElement.php index 7514ddfc..610753df 100644 --- a/src/PHPDraft/Model/RequestBodyElement.php +++ b/src/PHPDraft/Model/Elements/RequestBodyElement.php @@ -6,8 +6,9 @@ * @author Sean Molenaar */ -namespace PHPDraft\Model; +namespace PHPDraft\Model\Elements; +use PHPDraft\Model\DataStructureElement; class RequestBodyElement extends DataStructureElement { @@ -62,6 +63,13 @@ public function parse($object, &$dependencies) return $this; } + /** + * Print the request body as a string + * + * @param string $type The type of request + * + * @return string Request body + */ public function print_request($type = 'application/x-www-form-urlencoded') { if (is_array($this->value)) diff --git a/src/PHPDraft/Model/HTTPRequest.php b/src/PHPDraft/Model/HTTPRequest.php index cc42697a..f60074b9 100644 --- a/src/PHPDraft/Model/HTTPRequest.php +++ b/src/PHPDraft/Model/HTTPRequest.php @@ -8,6 +8,8 @@ namespace PHPDraft\Model; +use PHPDraft\Model\Elements\RequestBodyElement; + class HTTPRequest { /** @@ -32,13 +34,25 @@ class HTTPRequest * Body of the request (if POST or PUT) * @var RequestBodyElement[] */ - public $body; + public $body = []; + /** + * HTTPRequest constructor. + * + * @param Transition $parent Parent entity + */ public function __construct(&$parent) { $this->parent = &$parent; } + /** + * Fill class values based on JSON object + * + * @param \stdClass $object JSON object + * + * @return $this self-reference + */ public function parse($object) { $this->method = $object->attributes->method; @@ -66,6 +80,11 @@ public function parse($object) return $this; } + /** + * Parse the objects into a request body + * + * @param \stdClass[] $objects JSON objects + */ private function parse_structure($objects) { foreach ($objects as $object) @@ -79,6 +98,13 @@ private function parse_structure($objects) } } + /** + * Generate a cURL command for the HTTP request + * + * @param string $base_url URL to the base server + * + * @return string An executable cURL command + */ public function get_curl_command($base_url) { $options = []; @@ -95,7 +121,7 @@ public function get_curl_command($base_url) $options[] = '-H "'.$header.': '.$value. '"'; } $options[] = '-v'; - return htmlspecialchars('curl '.join(' ', $options). ' "'.$base_url.$this->parent->build_url().'"'); + return htmlspecialchars('curl '.join(' ', $options). ' "'.$this->parent->build_url($base_url).'"'); } diff --git a/src/PHPDraft/Model/HTTPResponse.php b/src/PHPDraft/Model/HTTPResponse.php index f1014578..a16b9b57 100644 --- a/src/PHPDraft/Model/HTTPResponse.php +++ b/src/PHPDraft/Model/HTTPResponse.php @@ -11,7 +11,7 @@ class HTTPResponse { /** - * Description + * HTTP Status code * @var int */ public $statuscode; @@ -45,6 +45,13 @@ public function __construct($parent) $this->parent = &$parent; } + /** + * Fill class values based on JSON object + * + * @param \stdClass $object JSON object + * + * @return $this self-reference + */ public function parse($object) { $this->statuscode = intval($object->attributes->statusCode); diff --git a/src/PHPDraft/Model/Resource.php b/src/PHPDraft/Model/Resource.php index 1d939c43..57e2c8cb 100644 --- a/src/PHPDraft/Model/Resource.php +++ b/src/PHPDraft/Model/Resource.php @@ -2,7 +2,7 @@ /** * This file contains the Resource.php * - * @package php-drafter\SOMETHING + * @package PHPDraft\Model * @author Sean Molenaar */ @@ -27,6 +27,13 @@ public function __construct(&$parent) $this->parent = $parent; } + /** + * Fill class values based on JSON object + * + * @param \stdClass $object JSON object + * + * @return $this self-reference + */ function parse($object) { parent::parse($object); @@ -37,7 +44,7 @@ function parse($object) { if ($item->element === 'copy') continue; $transition = new Transition($this); - array_push($this->children, $transition->parse($item)); + $this->children[] = $transition->parse($item); } return $this; diff --git a/src/PHPDraft/Model/Tests/DataStructureElementTest.php b/src/PHPDraft/Model/Tests/DataStructureElementTest.php index b5c4bb86..35bfb6e6 100644 --- a/src/PHPDraft/Model/Tests/DataStructureElementTest.php +++ b/src/PHPDraft/Model/Tests/DataStructureElementTest.php @@ -2,7 +2,7 @@ /** * This file contains the APIBlueprintElementTest.php * - * @package php-drafter\Model + * @package PHPDraft\Model * @author Sean Molenaar */ @@ -72,6 +72,11 @@ public function testSuccesfulDependencyCheck($object, $expected) $this->assertSame($dep, $expected); } + /** + * Provide objects to parse including expected outcome + * + * @return array + */ public function parseObjectProvider() { $return = []; @@ -101,6 +106,10 @@ public function parseObjectProvider() return $return; } + /** + * JSON to parse including expected gathered dependency list + * @return array + */ public function parseObjectDepProvider() { $return = []; diff --git a/src/PHPDraft/Model/Transition.php b/src/PHPDraft/Model/Transition.php index 7873d713..b0592842 100644 --- a/src/PHPDraft/Model/Transition.php +++ b/src/PHPDraft/Model/Transition.php @@ -65,6 +65,13 @@ public function __construct(&$parent) $this->parent = $parent; } + /** + * Fill class values based on JSON object + * + * @param \stdClass $object JSON object + * + * @return $this self-reference + */ function parse($object) { parent::parse($object); @@ -121,7 +128,14 @@ function parse($object) return $this; } - public function build_url() + /** + * Build a URL based on the URL variables given + * + * @param string $base_url the URL to which the URL variables apply + * + * @return string a HTML representation of the transition URL + */ + public function build_url($base_url = '') { $url = $this->href; foreach ($this->url_variables as $key => $value) @@ -137,14 +151,26 @@ public function build_url() $url = preg_replace('/({' . $key . '})/', '' . urlencode($urlvalue) . '', $url); } - return $url; + return $base_url.$url; } + /** + * Get the HTTP method of the child request + * + * @return string HTTP Method + */ public function get_method() { return (isset($this->request->method)) ? $this->request->method : 'NONE'; } + /** + * Generate a cURL request to run the transition + * + * @param string $base_url base URL of the server + * + * @return string A cURL CLI command + */ public function get_curl_command($base_url) { return $this->request->get_curl_command($base_url); diff --git a/src/PHPDraft/HTML/default.php b/src/PHPDraft/Out/HTML/default.php similarity index 100% rename from src/PHPDraft/HTML/default.php rename to src/PHPDraft/Out/HTML/default.php diff --git a/src/PHPDraft/HTML/index.css b/src/PHPDraft/Out/HTML/index.css similarity index 100% rename from src/PHPDraft/HTML/index.css rename to src/PHPDraft/Out/HTML/index.css diff --git a/src/PHPDraft/Out/TemplateGenerator.php b/src/PHPDraft/Out/TemplateGenerator.php index 7ba335b5..3e24d379 100644 --- a/src/PHPDraft/Out/TemplateGenerator.php +++ b/src/PHPDraft/Out/TemplateGenerator.php @@ -16,30 +16,27 @@ class TemplateGenerator { /** * JSON object of the API blueprint - * * @var mixed */ protected $categories = []; /** * The template file to load - * * @var string */ protected $template; /** * The base URl of the API - * * @var */ protected $base_data; /** * Structures used in all data - * @var DataStructureElement + * @var DataStructureElement[] */ - protected $base_structures; + protected $base_structures = []; /** * TemplateGenerator constructor. @@ -52,9 +49,11 @@ public function __construct($template) } /** - * @param mixed $object + * Pre-parse objects needed and print HTML + * + * @param mixed $object JSON to parse from * - * @return string + * @return void */ public function get($object) { @@ -91,11 +90,16 @@ public function get($object) } } - include_once 'PHPDraft/HTML/' . $this->template . '.php'; - - return ''; + include_once 'PHPDraft/Out/HTML/' . $this->template . '.php'; } + /** + * Get an icon for a specific HTTP Method + * + * @param string $method HTTP method + * + * @return string class to represent the HTTP Method + */ function get_method_icon($method) { switch (strtolower($method)) @@ -119,6 +123,13 @@ function get_method_icon($method) return $class . ' ' . $method; } + /** + * Get a bootstrap class to represent the HTTP return code range + * + * @param int $response HTTP return code + * + * @return string Class to use + */ function get_response_status($response) { if ($response <= 299) @@ -136,9 +147,11 @@ function get_response_status($response) } /** + * Determine if an object should be printed + * * @param DataStructureElement $object Objects to print * - * @return string + * @return string Object representation */ function get_data_structure($object) { diff --git a/src/PHPDraft/Parse/ApibToJson.php b/src/PHPDraft/Parse/ApibToJson.php index 6fabcd72..fa561ddf 100644 --- a/src/PHPDraft/Parse/ApibToJson.php +++ b/src/PHPDraft/Parse/ApibToJson.php @@ -2,7 +2,7 @@ /** * This file contains the ApibToJson.php * - * @package torch-apidoc\SOMETHING + * @package PHPDraft\Parse * @author Sean Molenaar */ @@ -33,6 +33,8 @@ class ApibToJson /** * ApibToJson constructor. + * + * @param string $apib API Blueprint text */ public function __construct($apib) { @@ -42,7 +44,9 @@ public function __construct($apib) } /** - * @return string + * Parse the API Blueprint text to JSON + * + * @return string API Blueprint text */ public function parseToJson() { @@ -55,8 +59,7 @@ public function parseToJson() file_put_contents($tmp_dir . '/index.apib', $this->apib); if (!$this->drafter_location()) { - $fe = fopen('php://stderr', 'w'); - fwrite($fe, "Drafter was not installed!\n"); + file_put_contents('php://stderr', "Drafter was not installed!\n"); exit(1); } diff --git a/src/PHPDraft/Parse/JsonToHTML.php b/src/PHPDraft/Parse/JsonToHTML.php index eb69bdd8..15a86e4a 100644 --- a/src/PHPDraft/Parse/JsonToHTML.php +++ b/src/PHPDraft/Parse/JsonToHTML.php @@ -30,6 +30,8 @@ public function __construct($json) } /** + * Get the HTML representation of the JSON object + * * @param string $template Type of template to display. * * @return string HTML template to display @@ -40,6 +42,11 @@ public function get_html($template = 'default') return $gen->get($this->object); } + /** + * Gets the default template HTML + * + * @return string + */ function __toString() { return $this->get_html(); diff --git a/src/PHPDraft/Parse/Tests/ApibToJsonTest.php b/src/PHPDraft/Parse/Tests/ApibToJsonTest.php index e08d7cb6..e2fe0da7 100644 --- a/src/PHPDraft/Parse/Tests/ApibToJsonTest.php +++ b/src/PHPDraft/Parse/Tests/ApibToJsonTest.php @@ -12,6 +12,10 @@ use PHPUnit_Framework_TestCase; use ReflectionClass; +/** + * Class ApibToJsonTest + * @covers PHPDraft\Parse\ApibToJson + */ class ApibToJsonTest extends PHPUnit_Framework_TestCase { /** @@ -26,18 +30,27 @@ class ApibToJsonTest extends PHPUnit_Framework_TestCase */ protected $reflection; + /** + * Set up + */ public function setUp() { $this->class = new ApibToJson(file_get_contents(TEST_STATICS . '/apib')); $this->reflection = new ReflectionClass('PHPDraft\Parse\ApibToJson'); } + /** + * Tear down + */ public function tearDown() { unset($this->class); unset($this->reflection); } + /** + * Test if the value the class is initialized with is correct + */ public function testSetupCorrectly() { $property = $this->reflection->getProperty('apib'); @@ -45,11 +58,17 @@ public function testSetupCorrectly() $this->assertEquals(file_get_contents(TEST_STATICS . '/apib'), $property->getValue($this->class)); } + /** + * Check if the JSON is empty before parsing + */ public function testPreRunStringIsEmpty() { $this->assertEmpty($this->class->__toString()); } + /** + * Check if parsing the APIB to JSON gives the expected result + */ public function testParseToJSON() { $this->class->parseToJson(); diff --git a/src/PHPDraft/Parse/Tests/JsonToHTMLTest.php b/src/PHPDraft/Parse/Tests/JsonToHTMLTest.php index b03d3cb4..0012a85d 100644 --- a/src/PHPDraft/Parse/Tests/JsonToHTMLTest.php +++ b/src/PHPDraft/Parse/Tests/JsonToHTMLTest.php @@ -26,18 +26,27 @@ class JsonToHTMLTest extends PHPUnit_Framework_TestCase */ protected $reflection; + /** + * Set up + */ public function setUp() { $this->class = new JsonToHTML(file_get_contents(TEST_STATICS . '/json')); $this->reflection = new ReflectionClass('PHPDraft\Parse\JsonToHTML'); } + /** + * Tear down + */ public function tearDown() { unset($this->class); unset($this->reflection); } + /** + * Tests if the constructor sets the property correctly + */ public function testSetupCorrectly() { $property = $this->reflection->getProperty('object'); @@ -45,6 +54,9 @@ public function testSetupCorrectly() $this->assertEquals(json_decode(file_get_contents(TEST_STATICS . '/json')), $property->getValue($this->class)); } + /** + * Tests if the outputted HTM is as expected. + */ public function testParseToHTML() { $this->expectOutputString(file_get_contents(TEST_STATICS.'/html')); diff --git a/tests/phpunit.xml b/tests/phpunit.xml index 2466abbc..2d5b77ec 100755 --- a/tests/phpunit.xml +++ b/tests/phpunit.xml @@ -22,18 +22,22 @@ - ../src/Lunr/ + ../src/PHPDraft/ ../src/Mitchelf/ ../src/PHPDraft/Parse/Tests/ ../src/PHPDraft/Model/Tests/ + ../src/PHPDraft/Model/Elements/Tests/ + ../src/PHPDraft/Out/Tests/ + ../src/PHPDraft/Out/HTML/ + ../src/PHPDraft/In/Tests/ - * @license https://github.com/SMillerDev/Php-drafter/blob/master/LICENSE GPLv3 License + * @license https://github.com/SMillerDev/phpdraft/blob/master/LICENSE GPLv3 License */ $base = __DIR__ . '/..';