Skip to content

Commit 4f6ab9f

Browse files
sudiptochoudhurysudiptochoudhury
committed
### 0.0.8
- Fix for @method doc generation & markdown doc generation by removing redundant spaces and newlines - Introduce shorter description in @method doc
1 parent df5ede4 commit 4f6ab9f

File tree

3 files changed

+136
-30
lines changed

3 files changed

+136
-30
lines changed

‎CHANGELOG.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,4 +30,8 @@
3030

3131
### 0.0.7
3232
- Fix for @method doc generation
33-
- skip description in @method doc
33+
- skip description in @method doc
34+
35+
### 0.0.8
36+
- Fix for @method doc generation & markdown doc generation by removing redundant spaces and newlines
37+
- Introduce shorter description in @method doc

‎src/support/forge/api/Client.php‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -142,7 +142,7 @@ public function setDescription($descriptionOptions = [])
142142

143143
} catch (\Exception $ex) {
144144
} finally {
145-
$this->description = new Description($description, $options) ?: [];
145+
$this->description = new Description($description, $options) ? : [];
146146
}
147147

148148
}
@@ -197,6 +197,8 @@ public function __call($name, $arguments)
197197
* @param array $options
198198
*
199199
* @return bool|int
200+
*
201+
* @throws \Exception
200202
*/
201203
public function importApi($source = '', $destination = '', $options = [])
202204
{
@@ -212,7 +214,8 @@ public function importApi($source = '', $destination = '', $options = [])
212214
/**
213215
* @return array
214216
*/
215-
protected function getAllOptions() {
217+
protected function getAllOptions()
218+
{
216219
return [
217220
'clientOptions' => $this->options,
218221
'rootPath' => $this->rootPath,
@@ -225,14 +228,16 @@ protected function getAllOptions() {
225228
* @return string
226229
* @throws \ReflectionException
227230
*/
228-
private function getChildDir() {
231+
private function getChildDir()
232+
{
229233
return dirname((new \ReflectionClass(static::class))->getFileName());
230234
}
231235

232236
/**
233237
* @return string
234238
*/
235-
private function getDir() {
239+
private function getDir()
240+
{
236241
return __DIR__;
237242
}
238243
}

‎src/support/forge/api/Import.php‎

Lines changed: 122 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -33,15 +33,15 @@ class Import
3333
public function __construct($filePath = '', $options = [])
3434
{
3535

36-
foreach($options as $key => $item) {
36+
foreach ($options as $key => $item) {
3737
if (property_exists($this, $key)) {
3838
$this->{$key} = $item;
3939
}
4040
}
4141

4242
$data = '';
4343
if (empty($this->rootPath)) {
44-
$this->rootPath = realpath($this->getChildDir()). '/';
44+
$this->rootPath = realpath($this->getChildDir()) . '/';
4545
}
4646
$rootPath = $this->rootPath;
4747

@@ -133,29 +133,31 @@ protected function parseOperation($request = [])
133133
{
134134
$meta = [$request];
135135
$method = $request['method'];
136-
// $header = $request['header'];
136+
// $header = $request['header'];
137137
$body = $request['body'];
138138
$url = $request['url'];
139139
$data = [
140140
'httpMethod' => $method,
141141
'uri' => $this->parseUri($url, $meta),
142142
'responseModel' => 'getResponse',
143-
'parameters' => $this->parseParams($url['path'], $body['raw'], $meta),
143+
'parameters' => $this->parseParams($url, $body['raw'], $meta),
144144
];
145145
return $data;
146146

147147
}
148148

149149
/**
150-
* @param array $paths
150+
* @param array $url
151151
* @param string $bodyRaw
152152
* @param array $meta
153153
*
154154
* @return array
155155
*/
156-
protected function parseParams($paths = [], $bodyRaw = '', $meta = [])
156+
protected function parseParams($url = [], $bodyRaw = '', $meta = [])
157157
{
158+
$paths = $url['path'];
158159
$params = [];
160+
159161
foreach ($paths as $path) {
160162
if (!!preg_match('/^{/', $path) !== false) {
161163
$paramName = preg_replace('/^{|}$/', '', $path);
@@ -171,6 +173,7 @@ protected function parseParams($paths = [], $bodyRaw = '', $meta = [])
171173

172174
}
173175
}
176+
174177
$rawParams = json_decode($bodyRaw, true);
175178
if (!empty($rawParams)) {
176179
foreach ($rawParams as $paramName => $paramItem) {
@@ -185,6 +188,15 @@ protected function parseParams($paths = [], $bodyRaw = '', $meta = [])
185188
];
186189
}
187190
}
191+
192+
if (!empty($queryParams = ($url['query'] ?? null))) {
193+
foreach ($queryParams as $query) {
194+
if (!empty(preg_match('/^{/', $query['value']))) {
195+
$params[$query['key']] = ['location' => 'uri'];
196+
}
197+
}
198+
}
199+
188200
return $params;
189201

190202
}
@@ -197,7 +209,19 @@ protected function parseParams($paths = [], $bodyRaw = '', $meta = [])
197209
*/
198210
protected function parseUri($url, $meta = [])
199211
{
200-
return implode('/', array_slice($url['path'], 2));
212+
$uri = implode('/', array_slice($url['path'], 2));
213+
$queryString = '';
214+
215+
if (!empty($queryParams = ($url['query'] ?? null))) {
216+
$queries = [];
217+
foreach ($queryParams as $query) {
218+
$queries[] = "{$query['key']}={$query['value']}";
219+
}
220+
if (!empty($queries)) {
221+
$queryString = '?' . implode('&', $queries);
222+
}
223+
}
224+
return $uri . $queryString;
201225
}
202226

203227
/**
@@ -250,19 +274,20 @@ protected function parseApiName($api)
250274
*
251275
* @return array
252276
*/
253-
protected function generateDocs($operation, $api = [], $method = '') {
277+
protected function generateDocs($operation, $api = [], $method = '')
278+
{
254279

255-
// $baseUri = $this->clientOptions['base_url'] ?: '';
280+
// $baseUri = $this->clientOptions['base_url'] ?: '';
256281

257-
// $name = $api['name'];
258-
// $request = $api['request'];
259-
// $response = $api['response'];
282+
// $name = $api['name'];
283+
// $request = $api['request'];
284+
// $response = $api['response'];
260285
/** @var $method */
261286
/** @var $header */
262287
/** @var $body */
263288
/** @var $url */
264289
/** @var $description */
265-
// extract($request);
290+
// extract($request);
266291

267292
return compact('operation', 'api', 'method');
268293

@@ -275,25 +300,93 @@ protected function generateDocs($operation, $api = [], $method = '') {
275300
*
276301
* @return string
277302
*/
278-
protected function generateMethod($apiName, $operation = [], $api = []) {
303+
protected function generateMethod($apiName, $operation = [], $api = [])
304+
{
279305

280306
$method = [' * @method', 'array'];
281307

282308
$data = "";
283309
$request = $api['request'];
284-
$description = preg_replace('/[\r\n]/', ' ', $request['description']);
310+
$description = $this->sanitizeDescription($request['description'], ['noMarkdown' => true, 'shorten' => true]);
285311
$params = $operation['parameters'];
286312
if (!empty($params)) {
287313
$data = 'array $parameters';
288314
}
289315

290316
$method[] = "$apiName($data)";
291-
// $method[] = $description;
317+
$method[] = $description;
292318

293319
return implode("\t", $method);
294320

295321
}
296322

323+
/**
324+
* @param string $description
325+
* @param array $options
326+
*
327+
* @return string
328+
*/
329+
protected function sanitizeDescription($description = '', $options = [])
330+
{
331+
$defaults = ['noMarkdown' => false, 'shorten' => false];
332+
$options = array_merge($defaults, $options);
333+
334+
$pre = [
335+
'e' => ['/\[[^]]+\]\(\)/', ], 'r' => ['',]
336+
];
337+
$post = [
338+
'e' => ['/\s+/', '/^[\s]+|[\s]+$/', '/(<br\/>)+/', '/^(<br\/>)+|(<br\/>)+$/m'], 'r' =>
339+
[' ', '', '<br/>', '']
340+
];
341+
342+
$optionsReplaceMap = [
343+
'noMarkdown' => [
344+
'e' => ['/\[[^]]+\]\([^)]+\)/', '/[\r\n]+/'], 'r' => ['', ' ']
345+
],
346+
'noMarkdown-' => [
347+
'e' => ['/[\r\n]+/'], 'r' => ['<br/>']
348+
],
349+
'noMarkdownshorten' => [
350+
'e' => ['/\*{2,}[\s\S]+$/', '/\*+/'], 'r' => ['', '']
351+
],
352+
'noMarkdownshorten-' => [
353+
'e' => ['/\*+/'], 'r' => ['']
354+
],
355+
'noMarkdown-shorten' => [
356+
'e' => ['/\*{2,}[\s\S]+$/', '/<br\/>[\s\S]+$/'], 'r' => ['', '']
357+
],
358+
];
359+
360+
if (!empty($description)) {
361+
$regExps = array_merge([], $pre['e']);
362+
$replaces = array_merge([], $pre['r']);
363+
foreach($options as $key => $value) {
364+
$value = $value ? '': '-';
365+
$keyValue = $key.$value;
366+
if (!empty($map = $optionsReplaceMap[$keyValue] ?? null)) {
367+
$regExps = array_merge($regExps, $map['e']);
368+
$replaces = array_merge($replaces, $map['r']);
369+
}
370+
foreach($options as $childKey => $childValue) {
371+
if ($key != $childKey) {
372+
$childValue = ($options[$childKey] ?? false) ? '': '-';
373+
$childKeyValue = $keyValue.$childKey.$childValue;
374+
if (!empty($childMap = $optionsReplaceMap[$childKeyValue] ?? null)) {
375+
$regExps = array_merge($regExps, $childMap['e']);
376+
$replaces = array_merge($replaces, $childMap['r']);
377+
}
378+
}
379+
}
380+
}
381+
$regExps = array_merge($regExps, $post['e']);
382+
$replaces = array_merge($replaces, $post['r']);
383+
384+
$description = trim(preg_replace($regExps, $replaces, trim($description)));
385+
}
386+
387+
return $description;
388+
}
389+
297390
/**
298391
* @param string $string
299392
*
@@ -352,7 +445,7 @@ public function writeData($path = '', $options = [])
352445
}
353446
$json = \GuzzleHttp\json_encode($this->data, JSON_PRETTY_PRINT | JSON_ERROR_NONE | JSON_UNESCAPED_SLASHES);
354447

355-
// $options['skipDocs'] = true;
448+
// $options['skipDocs'] = true;
356449
if (empty($options['skipDocs'])) {
357450
$pathWihtouExtension = preg_replace('/\.[^.]+?$/', '', $path);
358451
$this->writeMDDocs($options['docsPath'] ?? ($pathWihtouExtension . '.md'));
@@ -367,7 +460,8 @@ public function writeData($path = '', $options = [])
367460
*
368461
* @return bool|int
369462
*/
370-
protected function writeMDDocs($path = '') {
463+
protected function writeMDDocs($path = '')
464+
{
371465

372466
if (empty($path)) {
373467
$path = realpath($this->rootPath . $this->DEFAULT_API_JSON_PATH);
@@ -390,17 +484,17 @@ protected function writeMDDocs($path = '') {
390484
$md[] = "|--------------------|----------------------|----------------|------------|";
391485

392486
$groups = $data['groups'];
393-
foreach($groups as $groupName => $group) {
487+
foreach ($groups as $groupName => $group) {
394488
$items = $group['items'];
395489
foreach ($items as $apiName => $item) {
396490
/** @var $api */
397491
/** @var $operation */
398492
/** @var $method */
399493
extract($item);
400494
$row = [];
401-
$row[] = $apiName . "(" . (empty($operation['parameters']) ? '' : 'Array') . ")";
495+
$row[] = $apiName . "(" . (empty($operation['parameters']) ? '' : 'array') . ")";
402496
$row[] = " \[{$operation['httpMethod']}\] {$operation['uri']} ";
403-
$row[] = preg_replace('/[\r\n]/', '', $api['request']['description']);
497+
$row[] = $this->sanitizeDescription($api['request']['description']);
404498
$row[] = implode("<br/>", array_keys($operation['parameters']));
405499
$row[] = '';
406500

@@ -418,7 +512,8 @@ protected function writeMDDocs($path = '') {
418512
*
419513
* @return bool|int
420514
*/
421-
protected function writeMethods($path = '') {
515+
protected function writeMethods($path = '')
516+
{
422517

423518
if (empty($path)) {
424519
$path = realpath($this->rootPath . $this->DEFAULT_API_JSON_PATH);
@@ -432,7 +527,7 @@ protected function writeMethods($path = '') {
432527
}
433528

434529

435-
$methods = array_merge(["<?php", "/** "], $this->methodData ?: [], [" */", ""]);
530+
$methods = array_merge(["<?php", "/** "], $this->methodData ? : [], [" */", ""]);
436531
$methodText = implode("\n", $methods);
437532

438533
return file_put_contents($path, $methodText);
@@ -442,14 +537,16 @@ protected function writeMethods($path = '') {
442537
* @return string
443538
* @throws \ReflectionException
444539
*/
445-
private function getChildDir() {
540+
private function getChildDir()
541+
{
446542
return dirname((new \ReflectionClass(static::class))->getFileName());
447543
}
448544

449545
/**
450546
* @return string
451547
*/
452-
private function getDir() {
548+
private function getDir()
549+
{
453550
return __DIR__;
454551
}
455552

0 commit comments

Comments
 (0)