Skip to content

Commit 02d34fd

Browse files
mpociotmpociot
committed
Moved from Whiteboard to Documentarian
1 parent 6e7c50f commit 02d34fd

File tree

6 files changed

+388
-76
lines changed

6 files changed

+388
-76
lines changed

‎README.md

Lines changed: 18 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,30 @@
1-
## Laravel API Documentation Generator (WIP)
1+
# Documentarian
2+
#### Simply write beautiful API documentation.
3+
========
24

3-
`php artisan api:gen --routePrefix=settings/api/*`
5+
This project is a PHP port of the popular [Slate](https://github.com/tripit/slate) API documentation tool.
46

7+
> If PHP is not your thing and you're more into nodeJS, why not give [Whiteboard](https://github.com/mpociot/whiteboard) a try?
58
6-
### Install
9+
<a href="http://www.marcelpociot.com/whiteboard/"><img src="http://www.marcelpociot.com/git/whiteboard_responsive.jpg" style="width: 100%" alt="Documentarian" /></a>
710

8-
Require this package with composer using the following command:
11+
Check out a Documentarian [example API documentation](http://www.marcelpociot.com/whiteboard/).
912

10-
```bash
11-
composer require mpociot/laravel-apidoc-generator
12-
```
13-
Go to your `config/app.php` and add the service provider:
13+
The documentation is available at [http://marcelpociot.com/documentarian/installation](http://marcelpociot.com/documentarian/installation)
1414

15-
```php
16-
Mpociot\ApiDoc\ApiDocGeneratorServiceProvider::class
17-
```
1815

19-
### Usage
16+
### Slate / Whiteboard compatibility
17+
Since both Documentarian and Slate use regular markdown files to render the API documentation, your existing Slate API documentation should work just fine. If you encounter any issues, please [submit an issue](https://github.com/mpociot/documentarian/issues).
2018

19+
### In depth documentation
20+
For further documentation, read the [Slate Wiki](https://github.com/tripit/slate/wiki).
2121

22-
```
23-
php artisan api:generate
24-
{--output=public/docs : The output path for the generated documentation}
25-
{--routePrefix= : The route prefix to use for generation - * can be used as a wildcard}
26-
{--routes=* : The route names to use for generation - if no routePrefix is provided}
27-
{--actAsUserId= : The user ID to use for API response calls}
28-
```
22+
### Documentations built with Documentarian
2923

24+
Feel free to submit a PR with a link to your documentation.
3025

31-
### License
26+
### Contributors
3227

33-
The Laravel API Documentation Generator is free software licensed under the MIT license.
28+
Slate was built by [Robert Lord](https://lord.io) while at [TripIt](http://tripit.com).
29+
30+
Documentarian was built by Marcel Pociot.

‎composer.json

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"name": "mpociot/laravel-apidoc-generator",
2+
"name": "mpociot/laravel-apidoc-generators",
33
"license": "MIT",
44
"description": "Generate beautiful API documentation from your Laravel / Lumen application",
55
"keywords": ["API","Documentation","Laravel"],
@@ -13,7 +13,8 @@
1313
"require": {
1414
"php": ">=7.0.0",
1515
"laravel/framework": "~5.0",
16-
"phpdocumentor/reflection-docblock": "~2.0"
16+
"phpdocumentor/reflection-docblock": "~2.0",
17+
"mpociot/documentarian": "dev-master"
1718
},
1819
"require-dev": {
1920
"phpunit/phpunit": "~5.0",

‎src/Mpociot/ApiDoc/ApiDocGenerator.php

Lines changed: 89 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,18 @@ private function getRouteRules($route)
107107
return [];
108108
}
109109

110+
/**
111+
* @param $arr
112+
* @param $first
113+
* @param $last
114+
* @return string
115+
*/
116+
protected function fancy_implode($arr, $first, $last)
117+
{
118+
array_push($arr, implode($last, array_splice($arr, -2)));
119+
return implode($first, $arr);
120+
}
121+
110122
/**
111123
* @param $rule
112124
* @param $attributeData
@@ -121,43 +133,114 @@ protected function parseRule($rule, &$attributeData)
121133
case 'required':
122134
$attributeData['required'] = true;
123135
break;
136+
case 'accepted':
137+
$attributeData['type'] = 'boolean';
138+
break;
139+
case 'after':
140+
$attributeData['type'] = 'date';
141+
$attributeData['description'][] = 'Must be a date after: `' . date(DATE_RFC850, strtotime($parameters[0])) . '`';
142+
break;
143+
case 'alpha':
144+
$attributeData['description'][] = 'Only alphabetic characters allowed';
145+
break;
146+
case 'alpha_dash':
147+
$attributeData['description'][] = 'Allowed: alpha-numeric characters, as well as dashes and underscores.';
148+
break;
149+
case 'alpha_num':
150+
$attributeData['description'][] = 'Only alpha-numeric characters allowed';
151+
break;
124152
case 'in':
125-
$attributeData['description'][] = implode(' or ', $parameters);
153+
$attributeData['description'][] = $this->fancy_implode($parameters, ', ', ' or ');
126154
break;
127155
case 'not_in':
128-
$attributeData['description'][] = 'Not in: ' . implode(' or ', $parameters);
156+
$attributeData['description'][] = 'Not in: ' . $this->fancy_implode($parameters, ', ', ' or ');
129157
break;
130158
case 'min':
159+
$attributeData['type'] = 'numeric';
131160
$attributeData['description'][] = 'Minimum: `' . $parameters[0] . '`';
132161
break;
133162
case 'max':
163+
$attributeData['type'] = 'numeric';
134164
$attributeData['description'][] = 'Maximum: `' . $parameters[0] . '`';
135165
break;
136166
case 'between':
137-
$attributeData['description'][] = 'Between: `' . $parameters[0] . '` and ' . $parameters[1];
167+
$attributeData['type'] = 'numeric';
168+
$attributeData['description'][] = 'Between: `' . $parameters[0] . '` and `' . $parameters[1] . '`';
169+
break;
170+
case 'before':
171+
$attributeData['type'] = 'date';
172+
$attributeData['description'][] = 'Must be a date preceding: `' . date(DATE_RFC850, strtotime($parameters[0])) . '`';
138173
break;
139174
case 'date_format':
140-
$attributeData['description'][] = 'Date format: ' . $parameters[0];
175+
$attributeData['type'] = 'date';
176+
$attributeData['description'][] = 'Date format: `' . $parameters[0] . '`';
177+
break;
178+
case 'different':
179+
$attributeData['description'][] = 'Must have a different value than parameter: `' . $parameters[0] . '`';
180+
break;
181+
case 'digits':
182+
$attributeData['type'] = 'numeric';
183+
$attributeData['description'][] = 'Must have an exact length of `' . $parameters[0] . '`';
184+
break;
185+
case 'digits_between':
186+
$attributeData['type'] = 'numeric';
187+
$attributeData['description'][] = 'Must have a length between `' . $parameters[0] . '` and `' . $parameters[1] . '`';
188+
break;
189+
case 'image':
190+
$attributeData['description'][] = 'Must be an image (jpeg, png, bmp, gif, or svg)';
191+
break;
192+
case 'json':
193+
$attributeData['type'] = 'string';
194+
$attributeData['description'][] = 'Must be a valid JSON string.';
141195
break;
142196
case 'mimetypes':
143197
case 'mimes':
144-
$attributeData['description'][] = 'Allowed mime types: ' . implode(', ', $parameters);
198+
$attributeData['description'][] = 'Allowed mime types: ' . $this->fancy_implode($parameters, ', ', ' or ');
145199
break;
146200
case 'required_if':
147201
$attributeData['description'][] = 'Required if `' . $parameters[0] . '` is `' . $parameters[1] . '`';
148202
break;
203+
case 'required_unless':
204+
$attributeData['description'][] = 'Required unless `' . $parameters[0] . '` is `' . $parameters[1] . '`';
205+
break;
206+
case 'required_with':
207+
$attributeData['description'][] = 'Required if the parameters ' . $this->fancy_implode($parameters, ', ', ' or ') . ' are present.';
208+
break;
209+
case 'required_with_all':
210+
$attributeData['description'][] = 'Required if the parameters ' . $this->fancy_implode($parameters, ', ', ' and ') . ' are present.';
211+
break;
212+
case 'required_without':
213+
$attributeData['description'][] = 'Required if the parameters ' . $this->fancy_implode($parameters, ', ', ' or ') . ' are not present.';
214+
break;
215+
case 'required_without_all':
216+
$attributeData['description'][] = 'Required if the parameters ' . $this->fancy_implode($parameters, ', ', ' and ') . ' are not present.';
217+
break;
218+
case 'same':
219+
$attributeData['description'][] = 'Must be the same as `' . $parameters[0] . '`';
220+
break;
221+
case 'size':
222+
$attributeData['description'][] = 'Must have the size of `' . $parameters[0] . '`';
223+
break;
224+
case 'timezone':
225+
$attributeData['description'][] = 'Must be a valid timezone identifier';
226+
break;
149227
case 'exists':
150228
$attributeData['description'][] = 'Valid ' . Str::singular($parameters[0]) . ' ' . $parameters[1];
151229
break;
152230
case 'active_url':
153231
$attributeData['type'] = 'url';
154232
break;
233+
case 'regex':
234+
$attributeData['type'] = 'string';
235+
$attributeData['description'][] = 'Must match this regular expression: `' . $parameters[0] . '`';
236+
break;
155237
case 'boolean':
238+
case 'array':
239+
case 'date':
156240
case 'email':
157241
case 'image':
158242
case 'string':
159243
case 'integer':
160-
case 'json':
161244
case 'numeric':
162245
case 'url':
163246
case 'ip':

‎src/Mpociot/ApiDoc/Commands/GenerateDocumentation.php

Lines changed: 6 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
use Illuminate\Console\Command;
66
use Illuminate\Support\Facades\Route;
77
use Mpociot\ApiDoc\ApiDocGenerator;
8+
use Mpociot\Documentarian\Documentarian;
89
use phpDocumentor\Reflection\DocBlock;
910
use Symfony\Component\Process\Process;
1011

@@ -94,20 +95,12 @@ private function writeMarkdown($parsedRoutes)
9495
{
9596
$outputPath = $this->option('output');
9697

97-
$markdown = view('apidoc::whiteboard')->with('parsedRoutes', $parsedRoutes);
98+
$documentarian = new Documentarian();
99+
100+
$markdown = view('apidoc::documentarian')->with('parsedRoutes', $parsedRoutes);
98101

99102
if (!is_dir($outputPath)) {
100-
$this->cloneWhiteboardRepository();
101-
102-
if ($this->confirm('Would you like to install the NPM dependencies?', true)) {
103-
$process = (new Process('npm set progress=false && npm install', $outputPath))->setTimeout(null);
104-
if ('\\' !== DIRECTORY_SEPARATOR && file_exists('/dev/tty') && is_readable('/dev/tty')) {
105-
$process->setTty(true);
106-
}
107-
$process->run(function ($type, $line) {
108-
$this->info($line);
109-
});
110-
}
103+
$documentarian->create($outputPath);
111104
}
112105

113106
file_put_contents($outputPath . DIRECTORY_SEPARATOR . 'source' . DIRECTORY_SEPARATOR . 'index.md', $markdown);
@@ -116,36 +109,9 @@ private function writeMarkdown($parsedRoutes)
116109

117110
$this->info('Generating API HTML code');
118111

119-
$process = (new Process('npm run-script generate', $outputPath))->setTimeout(null);
120-
if ('\\' !== DIRECTORY_SEPARATOR && file_exists('/dev/tty') && is_readable('/dev/tty')) {
121-
$process->setTty(true);
122-
}
123-
$process->run(function ($type, $line) {
124-
$this->info($line);
125-
});
112+
$documentarian->generate($outputPath);
126113

127114
$this->info('Wrote HTML documentation to: ' . $outputPath . '/public/index.html');
128115
}
129116

130-
/**
131-
* Clone the Whiteboard nodejs repository
132-
*/
133-
private function cloneWhiteboardRepository()
134-
{
135-
$outputPath = $this->option('output');
136-
137-
mkdir($outputPath, 0777, true);
138-
139-
// Clone whiteboard
140-
$this->info('Cloning whiteboard repository.');
141-
142-
$process = (new Process('git clone ' . self::WHITEBOARD_REPOSITORY . ' ' . $outputPath))->setTimeout(null);
143-
if ('\\' !== DIRECTORY_SEPARATOR && file_exists('/dev/tty') && is_readable('/dev/tty')) {
144-
$process->setTty(true);
145-
}
146-
$process->run(function ($type, $line) {
147-
$this->info($line);
148-
});
149-
}
150-
151117
}

‎src/resources/views/whiteboard.blade.php renamed to ‎src/resources/views/documentarian.blade.php

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
search: true
1111

1212
toc_footers:
13-
- <a href='http://github.com/mpociot/whiteboard'>Documentation Powered by Whiteboard</a>
13+
- <a href='http://github.com/mpociot/documentarian'>Documentation Powered by Whiteboard</a>
1414
---
1515

1616
# Info
@@ -36,6 +36,7 @@
3636
-d "{{$attribute}}"="dummy" \
3737
@endforeach
3838
@endif
39+
3940
```
4041

4142
```javascript
@@ -68,6 +69,7 @@
6869
### HTTP Request
6970
@foreach($parsedRoute['methods'] as $method)
7071
`{{$method}} {{$parsedRoute['uri']}}`
72+
7173
@endforeach
7274
@if(count($parsedRoute['parameters']))
7375

0 commit comments

Comments
 (0)