Skip to content

Commit afe4c8f

Browse files
sudiptochoudhurysudiptochoudhury
committed
### 0.2.3
- Option to skip an item - Option to skip generation of Documentation - Enhancement of filters - Option to add parameters default values externally - Documentation shows parameter default values - Documentation formatting with inline code style for methods and parameters
1 parent 2974650 commit afe4c8f

File tree

5 files changed

+118
-31
lines changed

5 files changed

+118
-31
lines changed

‎CHANGELOG.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,4 +63,11 @@
6363
### 0.2.2
6464
- Redistribute import from JSON into multible extensible functions
6565
- Cleaner code
66-
66+
67+
### 0.2.3
68+
- Option to skip an item
69+
- Option to skip generation of Documentation
70+
- Enhancement of filters
71+
- Option to add parameters default values externally
72+
- Documentation shows parameter default values
73+
- Documentation formatting with inline code style for methods and parameters

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

Lines changed: 49 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,6 @@ protected function importFromJson($filePath)
8989
$items = $json['item'];
9090

9191
foreach ($items as $itemIndex => $apiGroup) {
92-
9392
$apiGroupName = $this->applyFilter('GroupName', $apiGroup['name']);
9493
$apiGroupDescription = $this->applyFilter('GroupDescription', $apiGroup['description']);
9594
if (empty($docs[$apiGroupName])) {
@@ -100,6 +99,7 @@ protected function importFromJson($filePath)
10099

101100
$apiGroupItems = $apiGroup['item'];
102101
foreach ($apiGroupItems as $apiIndex => $api) {
102+
$api = $this->preProcessApi($api);
103103

104104
$commonParams = compact('api', 'apiIndex',
105105
'apiGroupItems', 'apiGroup', 'operations') +
@@ -113,11 +113,17 @@ protected function importFromJson($filePath)
113113
$commonParams['operation'] = $operation;
114114

115115
$commonParams['apiName'] = $apiName = $this->readApiName($commonParams);
116-
$operations[$apiName] = $operation;
117-
118-
$commonParams['apiDocMethod'] = $methods[$apiName] = $this->readPhpDocMethodItem($commonParams);
119-
$docs[$apiGroupName]['items'][$apiName] =$this->readMarkdownItem($commonParams);
120-
116+
$skipConfig = $this->deliberateSkips($commonParams);
117+
if (($skipConfig['operation'] ?? true) !== false) {
118+
$operations[$apiName] = $operation;
119+
}
120+
121+
if (($skipConfig['phpDoc'] ?? ($skipConfig['docs'] ?? true)) !== false) {
122+
$commonParams['phpDocMethod'] = $methods[$apiName] = $this->readPhpDocMethodItem($commonParams);
123+
}
124+
if (($skipConfig['mdDoc'] ?? ($skipConfig['docs'] ?? true)) !== false) {
125+
$docs[$apiGroupName]['items'][$apiName] =$this->readMarkdownItem($commonParams);
126+
}
121127
}
122128
}
123129

@@ -133,6 +139,14 @@ protected function importFromJson($filePath)
133139
return $data;
134140
}
135141

142+
/**
143+
* @param array $params
144+
*
145+
* @return array
146+
*/
147+
protected function deliberateSkips($params = []) {
148+
return [];
149+
}
136150
/**
137151
* @param array $params
138152
*
@@ -143,16 +157,29 @@ protected function readApiName($params = []) {
143157
/** @var $apiGroup */
144158
/** @var $operations */
145159
extract($params);
160+
$exists = [];
146161
$apiName = $this->applyFilter('Name', $this->parseApiName($api), compact('api', 'apiGroup'));
147162
if (isset($operations[$apiName])) {
148-
var_dump("Exists...$apiName");
163+
$exists[] = "Exists ... $apiName [{$api['name']}]";
149164
$apiName = $this->applyFilter('Slug', $this->sluggify($api['name']), compact('api', 'apiGroup'));
150-
var_dump(' named...'. $apiName);
165+
$exists[] = " Named it to - ";
166+
$exists[] = $apiName;
151167
}
152168
$apiName = $this->applyFilter('FinalName', $apiName, compact('api', 'apiGroup'));
169+
if (!empty($exists) && end($exists) !== $apiName) {
170+
$exists[] = ", but again renamed by filter to - $apiName.";
171+
}
153172
if (isset($operations[$apiName])) {
154-
var_dump("Still exists...replacing ... $apiName with {$apiName}_new ");
155-
$apiName .= '_new';
173+
do {
174+
if (!empty($exists)) {
175+
$exists[] = " ! still";
176+
}
177+
$exists[] = " duplicate ! renaming to _{$apiName} [{$api['name']}].";
178+
$apiName = '_' . $apiName;
179+
} while (isset($operations[$apiName]));
180+
}
181+
if (!empty($exists)) {
182+
// var_dump(implode("", $exists));
156183
}
157184
return $apiName;
158185
}
@@ -166,7 +193,7 @@ protected function readOperationItem($params = []) {
166193
/** @var $api */
167194
extract($params);
168195
$request = $api['request'];
169-
$operation = $this->parseOperation($request);
196+
$operation = $this->parseOperation($request, $params);
170197
$operation = $this->applyFilter('Operation', $operation, $params);
171198
return $operation;
172199
}
@@ -195,10 +222,10 @@ protected function readMarkdownItem($params = []) {
195222
/** @var $apiName */
196223
/** @var $api */
197224
/** @var $operation */
198-
/** @var $apiDocMethod */
225+
/** @var $phpDocMethod */
199226
extract($params);
200227

201-
$md = $this->generateDocs($apiName, $operation, $api, $apiDocMethod);
228+
$md = $this->generateDocs($apiName, $operation, $api, $phpDocMethod ?? '');
202229
$md = $this->applyFilter('DocMDItem', $md, $params);
203230
return $md;
204231
}
@@ -234,8 +261,16 @@ protected function readGlobalInfo($params = []) {
234261
* @return mixed
235262
*/
236263
protected function readGlobalTitle($params = []) {
237-
return $this->applyFilter('Title', $params['name']);
264+
return $this->applyFilter('Title', $params['name']);
238265
}
239266

267+
/**
268+
* @param $api
269+
*
270+
* @return mixed
271+
*/
272+
protected function preProcessApi($api) {
273+
return $api;
274+
}
240275

241276
}

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

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ trait DefaultFilters
1414
*/
1515
public function filterDocMDLayoutTitle($default, $details)
1616
{
17-
$md = ['##' . $details['data']['title']];
17+
$md = ['## ' . $details['data']['title']];
1818
$md[] = "";
1919
return $md;
2020
}
@@ -56,11 +56,28 @@ protected function filterDocMDLayoutTable($default, $details)
5656
/** @var $method string the function name */
5757
/** @var $endpoint */
5858
/** @var $parameters */
59+
/** @var $defaults */
5960
/** @var $description */
6061
extract($item);
62+
63+
$parameters = array_map(function ($item) {
64+
return "`{$item}`";
65+
}, $parameters);
66+
67+
if (!empty($defaults)) {
68+
foreach ($parameters as $index => &$param) {
69+
if (isset($defaults[$param])) {
70+
$param = "{$param} \[default: `{$defaults[$param]}`\]";
71+
}
72+
}
73+
}
74+
75+
$method = "`{$method}`";
76+
6177
$row = [];
6278
$row[] = implode('<br/>', [$method, $endpoint]);
63-
$row[] = implode("<br/>", $parameters);
79+
$params = implode("<br/>", $parameters) ?: '\[none\]';
80+
$row[] = $params;
6481
$row[] = $description;
6582
$row[] = '';
6683

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

Lines changed: 33 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,13 @@ trait Parsers
88
{
99
/**
1010
* @param array $request
11+
* @param array $params
1112
*
1213
* @return array
1314
*/
14-
protected function parseOperation($request = [])
15+
protected function parseOperation($request = [], $params = [])
1516
{
16-
$meta = [$request];
17+
$meta = $params + compact('request');
1718
$method = $request['method'];
1819
// $header = $request['header'];
1920
$body = $request['body'];
@@ -44,6 +45,7 @@ protected function generateDocs($apiName, $operation, $api = [], $method = '')
4445
$row['method'] = $this->getMDApiName($apiName, $operation, $api, $method);
4546
$row['endpoint'] = $this->getMDApiEndpoint($apiName, $operation, $api, $method);
4647
$row['parameters'] = $this->getMDApiParams($apiName, $operation, $api, $method);
48+
$row['defaults'] = $this->getMDApiParamDefaults($apiName, $operation, $api, $method);
4749
$row['description'] = $this->getMDDescription($apiName, $operation, $api, $method);
4850

4951
return $row;
@@ -60,18 +62,20 @@ protected function generateDocs($apiName, $operation, $api = [], $method = '')
6062
protected function generateMethod($apiName, $operation = [], $api = [])
6163
{
6264

65+
$filterParams = compact('apiName', 'operation', 'api');
6366
$method = [' * @method', 'array'];
6467

6568
$data = "";
6669
$request = $api['request'];
67-
$description = $this->applyFilter('DocMethodDescription',
68-
$this->sanitizeDescription($request['description'], ['noMarkdown' => true, 'shorten' => true]));
69-
$params = $this->applyFilter('DocMethodParams', $operation['parameters']);
70+
$description = $this->sanitizeDescription($request['description'], ['noMarkdown' => true, 'shorten' => true]);
71+
$description = $this->applyFilter('DocMethodDescription', $description, $filterParams);
72+
$params = $this->applyFilter('DocMethodParams', $operation['parameters'], $filterParams);
73+
$filterParams['params'] = $params;
7074
if (!empty($params)) {
71-
$data = $this->applyFilter('DocMethodData', 'array $parameters', $params);
75+
$data = $this->applyFilter('DocMethodData', 'array $parameters', $filterParams);
7276
}
7377

74-
$method[] = $this->applyFilter('DocMethodSignature', "$apiName($data)", compact('apiName', 'params'));
78+
$method[] = $this->applyFilter('DocMethodSignature', "$apiName($data)", $filterParams);
7579
$method[] = $description;
7680

7781
return implode("\t", $method);
@@ -88,6 +92,7 @@ protected function generateMethod($apiName, $operation = [], $api = [])
8892
protected function parseParams($url = [], $bodyRaw = '', $meta = [])
8993
{
9094
$paths = $url['path'];
95+
$defaults = $url['defaults'] ?? [];
9196
$params = [];
9297

9398
foreach ($paths as $path) {
@@ -131,8 +136,13 @@ protected function parseParams($url = [], $bodyRaw = '', $meta = [])
131136
}
132137
}
133138

134-
$this->applyFilter('Params', $params, $meta + ['body' => $bodyRaw]);
139+
foreach($params as $key => $item) {
140+
if (isset($defaults[$key])) {
141+
$params[$key]['default'] = $defaults[$key];
142+
}
143+
}
135144

145+
$params = $this->applyFilter('Params', $params, $meta + ['body' => $bodyRaw]);
136146
return $params;
137147

138148
}
@@ -162,7 +172,7 @@ protected function parseUri($url, $meta = [])
162172
}
163173

164174
$uriFinal = $uri . $queryString;
165-
$this->applyFilter('Uri', $uriFinal, $meta);
175+
$uriFinal = $this->applyFilter('Uri', $uriFinal, $meta);
166176
return $uriFinal;
167177
}
168178

@@ -360,5 +370,19 @@ protected function getMDApiParams($apiName, $operation, $api, $method)
360370
return $params;
361371
}
362372

373+
protected function getMDApiParamDefaults($apiName, $operation, $api, $method)
374+
{
375+
$defaults = [];
376+
$params = $operation['parameters'];
377+
foreach($params as $key => $item) {
378+
if (isset($item['default'])) {
379+
$defaults[$key] = $item['default'];
380+
}
381+
}
382+
383+
$params = $this->applyFilter('DocMDParamDefaults', $defaults, compact('operation', 'api', 'method'));
384+
return $defaults;
385+
}
386+
363387

364388
}

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

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -54,11 +54,15 @@ public function writeDefinition($path = '', $options = [])
5454

5555
$json = \GuzzleHttp\json_encode($data, JSON_PRETTY_PRINT | JSON_ERROR_NONE | JSON_UNESCAPED_SLASHES);
5656

57-
// $options['skipDocs'] = true;
58-
if (empty($options['skipDocs'])) {
59-
$pathWihtoutExtension = preg_replace('/\.[^.]+?$/', '', $path);
60-
$this->writeMarkdownDocs($options['docsPath'] ?? ($pathWihtoutExtension . '.md'));
61-
$this->writePHPDocMethod($options['methodsPath'] ?? ($pathWihtoutExtension . '.php'));
57+
// $options['skipDocs'] = true;
58+
$pathWihtoutExtension = preg_replace('/\.[^.]+?$/', '', $path);
59+
60+
if (empty($options['skipPhpDoc'] ?? $options['skipDocs'] ?? false)) {
61+
$this->writeMarkdownDocs($options['mdDocPath'] ?? ($pathWihtoutExtension . '.md'));
62+
}
63+
64+
if (empty($options['skipMDDoc'] ?? ($options['skipDocs'] ?? false))) {
65+
$this->writePHPDocMethod($options['phpDocPath'] ?? ($pathWihtoutExtension . '.php'));
6266
}
6367

6468
return file_put_contents($path, $json);

0 commit comments

Comments
 (0)