Magento Extensions Rating 2024
Magento 2 Documentation  2.3
Documentation for Magento 2 CMS v2.3 (December 2018)
DocumentationGenerator.php
Go to the documentation of this file.
1 <?php
7 namespace Magento\TestFramework\TestCase\Webapi\Adapter\Rest;
8 
13 class DocumentationGenerator
14 {
23  public function generateDocumentation($httpMethod, $resourcePath, $arguments, $response)
24  {
25  $content = $this->generateHtmlContent($httpMethod, $resourcePath, $arguments, $response);
26  $filePath = $this->generateFileName($resourcePath);
27  if ($filePath === null) {
28  return;
29  }
30  if (!is_writable(dirname($filePath))) {
31  throw new \RuntimeException('Cannot write to documentation directory.');
32  } elseif (file_exists($filePath)) {
33  $fileContent = file_get_contents($filePath);
34  $endHtml = $this->generateHtmlFooter();
35  $fileContent = str_replace($endHtml, '', $fileContent);
36  $content = "{$fileContent}{$content}";
37  unlink($filePath);
38  file_put_contents($filePath, $content, FILE_APPEND);
39  } else {
40  file_put_contents($filePath, $content, FILE_APPEND);
41  }
42  }
43 
53  protected function generateHtmlContent($httpMethod, $resourcePath, $arguments, $response)
54  {
55  if (empty($arguments)) {
56  $arguments = 'This call does not accept a request body.';
57  $requestParametersHtml = '';
58  } else {
59  $requestParameters = $this->retrieveParametersAsHtml($arguments);
60  $arguments = json_encode($arguments, JSON_PRETTY_PRINT);
61  $requestParametersHtml = <<<HTML
62  <table class="docutils field-list" frame="void" rules="none" width="400">
63  <colgroup>
64  <col width="35%" class="field-name">
65  <col width="65%" class="field-body">
66  </colgroup>
67  <tbody valign="top">
68  <tr class="field-odd field">
69  <th class="field-name">Request parameters:</th>
70  <td class="field-body">
71  <ul class="first last simple">
72  {$requestParameters}
73  </ul>
74  </td>
75  </tr>
76  </tbody>
77  </table>
78 HTML;
79  }
80  if (is_array($response)) {
81  $responseArrayKeys = array_keys($response);
82  $responseParameters = "Parameters should be specified manually.";
83  foreach ($responseArrayKeys as $key) {
84  if (!is_int($key)) {
85  $responseParameters = '';
86  break;
87  }
88  }
89  }
90  if (empty($responseParameters)) {
91  $responseParameters = $this->retrieveParametersAsHtml($response);
92  }
93  $response = json_encode($response, JSON_PRETTY_PRINT);
94  $responseParametersHtml = <<<HTML
95  <table class="docutils field-list" frame="void" rules="none" width="400">
96  <colgroup>
97  <col width="35%" class="field-name">
98  <col width="65%" class="field-body">
99  </colgroup>
100  <tbody valign="top">
101  <tr class="field-odd field">
102  <th class="field-name">Response attributes:</th>
103  <td class="field-body">
104  <ul class="first last simple">
105  {$responseParameters}
106  </ul>
107  </td>
108  </tr>
109  </tbody>
110  </table>
111 HTML;
112  $resourcePath = urldecode($resourcePath);
113  $resource = str_replace('/', '-', preg_replace('#/\w*/V\d+/(.*)#', '${1}', $resourcePath));
114  $lowerCaseResource = strtolower($resource);
115  $lowerCaseMethod = strtolower($httpMethod);
116  $beginningHtml = <<<HTML
117 <div class="col-xs-9" role="main">
118  <div class="bs-docs-section">
119 HTML;
120  $headingHtml = <<<HTML
121  <h2 class="api2" id="$lowerCaseResource">$resource</h2>
122  <h3 class="api3" id="$lowerCaseMethod-$lowerCaseResource">$httpMethod $resourcePath</h3>
123  <h4 class="api4">Request</h4>
124 HTML;
125  $responseHtml = <<<HTML
126  <h4 class="api4" id=”$lowerCaseResource-response>Response</h4>
127 HTML;
128  $requestResponseParametersHtml = <<<HTML
129  <h3 class="api3" id="$lowerCaseResource-parameters">Request and response parameters</h3>
130 HTML;
131  $endHtml = $this->generateHtmlFooter();
132  $content = "{$beginningHtml}{$headingHtml}<pre>{$arguments}</pre>{$responseHtml}<pre>{$response}"
133  . "</pre>{$requestResponseParametersHtml}{$requestParametersHtml}{$responseParametersHtml}{$endHtml}";
134  return $content;
135  }
136 
142  protected function generateHtmlFooter()
143  {
144  $endHtml = <<<HTML
145  <h3 class="api3" id="products-responses">Response codes</h3>
146  <table class="docutils field-list" frame="void" rules="none" width="400">
147  <colgroup>
148  <col width="35%" class="field-name">
149  <col width="65%" class="field-body">
150  </colgroup>
151  <tbody valign="top">
152  <tr class="field-odd field">
153  <th class="field-name">Normal response codes:</th>
154  <td class="field-body">
155  <ul class="first last simple">
156  <li><strong>SUCCESS_CODE</strong> - SUCCESS_DESCRIPTION</li>
157  </ul>
158  </td>
159  </tr>
160  </tbody>
161  </table>
162  <table class="docutils field-list" frame="void" rules="none" width="400">
163  <colgroup>
164  <col width="35%" class="field-name">
165  <col width="65%" class="field-body">
166  </colgroup>
167  <tbody valign="top">
168  <tr class="field-odd field">
169  <th class="field-name">Error response codes:</th>
170  <td class="field-body">
171  <ul class="first last simple">
172  <li><strong>ERROR_CODE</strong> - ERROR_DESCRIPTION</li>
173  </ul>
174  </td>
175  </tr>
176  </tbody>
177  </table>
178  </div>
179 </div>
180 HTML;
181  return $endHtml;
182  }
183 
190  protected function generateFileName()
191  {
192  $varDir = realpath(__DIR__ . '/../../../../../../..') . '/var';
193  $documentationDir = $varDir . '/log/rest-documentation/';
194  $debugBackTrace = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS);
195  $pathToFile = $documentationDir;
196  $fileName = null;
197  foreach ($debugBackTrace as $traceItem) {
199  if (count($traceItem) == 3) {
201  $fileName = lcfirst(substr($traceItem['function'], 4));
203  $pathToFile .= str_replace('\\', '/', substr($traceItem['class'], 0, -4)) . '/';
204  break;
205  }
206  }
207  if (!file_exists($pathToFile)) {
208  if (!mkdir($pathToFile, 0755, true)) {
209  throw new \RuntimeException('Unable to create missing directory for REST documentation generation');
210  }
211  }
212  if ($fileName !== null) {
213  $filePath = $pathToFile . $fileName . '.html';
214  return $filePath;
215  }
216  return null;
217  }
218 
225  protected function retrieveParametersAsHtml($parameters)
226  {
227  $parametersAsHtml = '';
228  if (is_array($parameters)) {
229  foreach (array_keys($parameters) as $parameter) {
230  $parametersAsHtml = $parametersAsHtml . '<li><strong>' . $parameter .
231  '</strong> (<em>Change type manually!</em>) TBD.</li>';
232  }
233  } else {
234  $parametersAsHtml = '<li><strong>' . 'scalar_value' .
235  '</strong> (<em>Change type manually!</em>) TBD.</li>';
236  }
237  return $parametersAsHtml;
238  }
239 }
$response
$response
Definition: 404.php:11
elseif
elseif(isset( $params[ 'redirect_parent']))
Definition: iframe.phtml:17
__DIR__
defined('TESTS_BP')||define('TESTS_BP' __DIR__
Definition: _bootstrap.php:60
Magento\TestFramework\TestCase\Webapi\Adapter\Rest\DocumentationGenerator\generateHtmlContent
generateHtmlContent($httpMethod, $resourcePath, $arguments, $response)
Definition: DocumentationGenerator.php:53
$resource
$resource
Definition: bulk.php:12
$fileName
$fileName
Definition: translate.phtml:15
Magento\TestFramework\TestCase\Webapi\Adapter\Rest\DocumentationGenerator\generateDocumentation
generateDocumentation($httpMethod, $resourcePath, $arguments, $response)
Definition: DocumentationGenerator.php:23
$varDir
if(!isset($_GET['template'])) $varDir
Definition: export.php:11
Magento\Framework\Backup\is_writable
is_writable($path)
Definition: io.php:25
$content
$content
Definition: downloadable_product_with_files_and_sample_url.php:93
$arguments
$arguments
Definition: final_price.phtml:24
Magento\Setup\Module\I18n\Pack\Writer\File\mkdir
mkdir($pathname, $mode=0777, $recursive=false, $context=null)
Definition: ioMock.php:25