Skip to content

Commit bafb73f

Browse files
shalvahshalvah
authored
Merge pull request #646 from mpociot/fix-rebuild
Update rebuild command to work with new docs locations
2 parents 778c0b5 + 86b8254 commit bafb73f

File tree

4 files changed

+72
-103
lines changed

4 files changed

+72
-103
lines changed

‎docs/migrating.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,10 @@ Note: This isn't meant to be an exhaustive guide to the changes in v4. Please se
88
## Configuration
99
- Rename your old config file (for instance to `apidoc.old.php`). Publish the new config file via `php artisan vendor:publish --provider="Mpociot\ApiDoc\ApiDocGeneratorServiceProvider" --tag=apidoc-config`. Then copy over any changes you've made in the old one and delete it when you're done.
1010

11+
- Remove the `output` key. Source files now go to `resources/docs/source` and generated docs go to either `public/docs/` or `resources/views/apidoc`.
12+
13+
- Make sure the `type` value is set appropriately. See [the docs](config.html#type).
14+
1115
- Remove the `bindings` section. It has been superseded by the `@urlParam` annotation, which works similarly to the existing `@queryParam` annotation. See [the docs](documenting.html#specifying-request-parameters)
1216

1317
- Remove the `response_calls.bindings` section. Use the `Example: ` feature of `@urlParam` to specify the value you want to be used in response calls.

‎src/Commands/GenerateDocumentation.php‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -78,12 +78,11 @@ public function handle()
7878
return $group->first()['metadata']['groupName'];
7979
}, SORT_NATURAL);
8080
$writer = new Writer(
81-
$groupedRoutes,
82-
$this->option('force'),
8381
$this,
84-
$this->docConfig
82+
$this->docConfig,
83+
$this->option('force')
8584
);
86-
$writer->writeDocs();
85+
$writer->writeDocs($groupedRoutes);
8786
}
8887

8988
/**

‎src/Commands/RebuildDocumentation.php‎

Lines changed: 8 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -3,54 +3,27 @@
33
namespace Mpociot\ApiDoc\Commands;
44

55
use Illuminate\Console\Command;
6-
use Mpociot\Documentarian\Documentarian;
6+
use Mpociot\ApiDoc\Tools\DocumentationConfig;
7+
use Mpociot\ApiDoc\Writing\Writer;
78

89
class RebuildDocumentation extends Command
910
{
10-
/**
11-
* The name and signature of the console command.
12-
*
13-
* @var string
14-
*/
1511
protected $signature = 'apidoc:rebuild';
1612

17-
/**
18-
* The console command description.
19-
*
20-
* @var string
21-
*/
2213
protected $description = 'Rebuild your API documentation from your markdown file.';
2314

24-
/**
25-
* Create a new command instance.
26-
*
27-
* @return void
28-
*/
29-
public function __construct()
30-
{
31-
parent::__construct();
32-
}
33-
34-
/**
35-
* Execute the console command.
36-
*
37-
* @return false|null
38-
*/
3915
public function handle()
4016
{
41-
$outputPath = config('apidoc.output');
42-
43-
$documentarian = new Documentarian();
44-
45-
if (! is_dir($outputPath)) {
46-
$this->error('There is no existing documentation available at '.$outputPath.'.');
17+
$sourceOutputPath = 'resources/docs/source';
18+
if (! is_dir($sourceOutputPath)) {
19+
$this->error('There is no existing documentation available at '.$sourceOutputPath.'.');
4720

4821
return false;
4922
}
50-
$this->info('Rebuilding API HTML code from '.$outputPath.'/source/index.md');
5123

52-
$documentarian->generate($outputPath);
24+
$this->info('Rebuilding API documentation from '.$sourceOutputPath.'/index.md');
5325

54-
$this->info('Wrote HTML documentation to: '.$outputPath.'/index.html');
26+
$writer = new Writer($this, new DocumentationConfig(config('apidoc')));
27+
$writer->writeHtmlDocs();
5528
}
5629
}

‎src/Writing/Writer.php‎

Lines changed: 57 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,6 @@
1010

1111
class Writer
1212
{
13-
/**
14-
* @var Collection
15-
*/
16-
protected $routes;
17-
1813
/**
1914
* @var Command
2015
*/
@@ -45,46 +40,59 @@ class Writer
4540
*/
4641
private $documentarian;
4742

48-
public function __construct(Collection $routes, bool $forceIt, Command $output, DocumentationConfig $config = null)
43+
/**
44+
* @var bool
45+
*/
46+
private $isStatic;
47+
48+
/**
49+
* @var string
50+
*/
51+
private $sourceOutputPath;
52+
53+
/**
54+
* @var string
55+
*/
56+
private $outputPath;
57+
58+
public function __construct(Command $output, DocumentationConfig $config = null, bool $forceIt = false)
4959
{
50-
$this->routes = $routes;
5160
// If no config is injected, pull from global
5261
$this->config = $config ?: new DocumentationConfig(config('apidoc'));
5362
$this->baseUrl = $this->config->get('base_url') ?? config('app.url');
5463
$this->forceIt = $forceIt;
5564
$this->output = $output;
5665
$this->shouldGeneratePostmanCollection = $this->config->get('postman.enabled', false);
5766
$this->documentarian = new Documentarian();
67+
$this->isStatic = $this->config->get('type') === 'static';
68+
$this->sourceOutputPath = 'resources/docs';
69+
$this->outputPath = $this->isStatic ? 'public/docs' : 'resources/views/apidoc';
5870
}
5971

60-
public function writeDocs()
72+
public function writeDocs(Collection $routes)
6173
{
6274
// The source files (index.md, js/, css/, and images/) always go in resources/docs/source.
6375
// The static assets (js/, css/, and images/) always go in public/docs/.
6476
// For 'static' docs, the output files (index.html, collection.json) go in public/docs/.
6577
// For 'laravel' docs, the output files (index.blade.php, collection.json)
6678
// go in resources/views/apidoc/ and storage/app/apidoc/ respectively.
67-
$isStatic = $this->config->get('type') === 'static';
6879

69-
$sourceOutputPath = 'resources/docs';
70-
$outputPath = $isStatic ? 'public/docs' : 'resources/views/apidoc';
80+
$this->writeMarkdownAndSourceFiles($routes);
7181

72-
$this->writeMarkdownAndSourceFiles($this->routes, $sourceOutputPath);
82+
$this->writeHtmlDocs();
7383

74-
$this->writeHtmlDocs($sourceOutputPath, $outputPath, $isStatic);
75-
76-
$this->writePostmanCollection($this->routes, $outputPath, $isStatic);
84+
$this->writePostmanCollection($routes);
7785
}
7886

7987
/**
8088
* @param Collection $parsedRoutes
8189
*
8290
* @return void
8391
*/
84-
public function writeMarkdownAndSourceFiles(Collection $parsedRoutes, string $sourceOutputPath)
92+
public function writeMarkdownAndSourceFiles(Collection $parsedRoutes)
8593
{
86-
$targetFile = $sourceOutputPath.'/source/index.md';
87-
$compareFile = $sourceOutputPath.'/source/.compare.md';
94+
$targetFile = $this->sourceOutputPath.'/source/index.md';
95+
$compareFile = $this->sourceOutputPath.'/source/.compare.md';
8896

8997
$infoText = view('apidoc::partials.info')
9098
->with('outputPath', 'docs')
@@ -125,8 +133,8 @@ public function writeMarkdownAndSourceFiles(Collection $parsedRoutes, string $so
125133
});
126134
}
127135

128-
$prependFileContents = $this->getMarkdownToPrepend($sourceOutputPath);
129-
$appendFileContents = $this->getMarkdownToAppend($sourceOutputPath);
136+
$prependFileContents = $this->getMarkdownToPrepend();
137+
$appendFileContents = $this->getMarkdownToAppend();
130138

131139
$markdown = view('apidoc::documentarian')
132140
->with('writeCompareFile', false)
@@ -138,11 +146,11 @@ public function writeMarkdownAndSourceFiles(Collection $parsedRoutes, string $so
138146
->with('showPostmanCollectionButton', $this->shouldGeneratePostmanCollection)
139147
->with('parsedRoutes', $parsedRouteOutput);
140148

141-
$this->output->info('Writing index.md and source files to: '.$sourceOutputPath);
149+
$this->output->info('Writing index.md and source files to: '.$this->sourceOutputPath);
142150

143-
if (! is_dir($sourceOutputPath)) {
151+
if (! is_dir($this->sourceOutputPath)) {
144152
$documentarian = new Documentarian();
145-
$documentarian->create($sourceOutputPath);
153+
$documentarian->create($this->sourceOutputPath);
146154
}
147155

148156
// Write output file
@@ -161,7 +169,7 @@ public function writeMarkdownAndSourceFiles(Collection $parsedRoutes, string $so
161169

162170
file_put_contents($compareFile, $compareMarkdown);
163171

164-
$this->output->info('Wrote index.md and source files to: '.$sourceOutputPath);
172+
$this->output->info('Wrote index.md and source files to: '.$this->sourceOutputPath);
165173
}
166174

167175
public function generateMarkdownOutputForEachRoute(Collection $parsedRoutes, array $settings): Collection
@@ -188,14 +196,14 @@ public function generateMarkdownOutputForEachRoute(Collection $parsedRoutes, arr
188196
return $parsedRouteOutput;
189197
}
190198

191-
protected function writePostmanCollection(Collection $parsedRoutes, string $outputPath, bool $isStatic): void
199+
protected function writePostmanCollection(Collection $parsedRoutes): void
192200
{
193201
if ($this->shouldGeneratePostmanCollection) {
194202
$this->output->info('Generating Postman collection');
195203

196204
$collection = $this->generatePostmanCollection($parsedRoutes);
197-
if ($isStatic) {
198-
$collectionPath = "{$outputPath}/collection.json";
205+
if ($this->isStatic) {
206+
$collectionPath = "{$this->outputPath}/collection.json";
199207
file_put_contents($collectionPath, $collection);
200208
} else {
201209
Storage::disk('local')->put('apidoc/collection.json', $collection);
@@ -220,90 +228,75 @@ public function generatePostmanCollection(Collection $routes)
220228
return $writer->getCollection();
221229
}
222230

223-
/**
224-
* @param string $sourceOutputPath
225-
*
226-
* @return string
227-
*/
228-
protected function getMarkdownToPrepend(string $sourceOutputPath): string
231+
protected function getMarkdownToPrepend(): string
229232
{
230-
$prependFile = $sourceOutputPath.'/source/prepend.md';
233+
$prependFile = $this->sourceOutputPath.'/source/prepend.md';
231234
$prependFileContents = file_exists($prependFile)
232235
? file_get_contents($prependFile)."\n" : '';
233236

234237
return $prependFileContents;
235238
}
236239

237-
/**
238-
* @param string $sourceOutputPath
239-
*
240-
* @return string
241-
*/
242-
protected function getMarkdownToAppend(string $sourceOutputPath): string
240+
protected function getMarkdownToAppend(): string
243241
{
244-
$appendFile = $sourceOutputPath.'/source/append.md';
242+
$appendFile = $this->sourceOutputPath.'/source/append.md';
245243
$appendFileContents = file_exists($appendFile)
246244
? "\n".file_get_contents($appendFile) : '';
247245

248246
return $appendFileContents;
249247
}
250248

251-
protected function copyAssetsFromSourceFolderToPublicFolder(string $sourceOutputPath, bool $isStatic = true): void
249+
protected function copyAssetsFromSourceFolderToPublicFolder(): void
252250
{
253251
$publicPath = 'public/docs';
254252
if (! is_dir($publicPath)) {
255253
mkdir($publicPath, 0777, true);
256254
mkdir("{$publicPath}/css");
257255
mkdir("{$publicPath}/js");
258256
}
259-
copy("{$sourceOutputPath}/js/all.js", "{$publicPath}/js/all.js");
260-
rcopy("{$sourceOutputPath}/images", "{$publicPath}/images");
261-
rcopy("{$sourceOutputPath}/css", "{$publicPath}/css");
257+
copy("{$this->sourceOutputPath}/js/all.js", "{$publicPath}/js/all.js");
258+
rcopy("{$this->sourceOutputPath}/images", "{$publicPath}/images");
259+
rcopy("{$this->sourceOutputPath}/css", "{$publicPath}/css");
262260

263261
if ($logo = $this->config->get('logo')) {
264-
if ($isStatic) {
262+
if ($this->isStatic) {
265263
copy($logo, "{$publicPath}/images/logo.png");
266264
}
267265
}
268266
}
269267

270-
protected function moveOutputFromSourceFolderToTargetFolder(string $sourceOutputPath, string $outputPath, bool $isStatic): void
268+
protected function moveOutputFromSourceFolderToTargetFolder(): void
271269
{
272-
if ($isStatic) {
270+
if ($this->isStatic) {
273271
// Move output (index.html, css/style.css and js/all.js) to public/docs
274-
rename("{$sourceOutputPath}/index.html", "{$outputPath}/index.html");
272+
rename("{$this->sourceOutputPath}/index.html", "{$this->outputPath}/index.html");
275273
} else {
276274
// Move output to resources/views
277-
if (! is_dir($outputPath)) {
278-
mkdir($outputPath);
275+
if (! is_dir($this->outputPath)) {
276+
mkdir($this->outputPath);
279277
}
280-
rename("{$sourceOutputPath}/index.html", "$outputPath/index.blade.php");
281-
$contents = file_get_contents("$outputPath/index.blade.php");
278+
rename("{$this->sourceOutputPath}/index.html", "$this->outputPath/index.blade.php");
279+
$contents = file_get_contents("$this->outputPath/index.blade.php");
282280
//
283281
$contents = str_replace('href="css/style.css"', 'href="/docs/css/style.css"', $contents);
284282
$contents = str_replace('src="js/all.js"', 'src="/docs/js/all.js"', $contents);
285283
$contents = str_replace('src="images/', 'src="/docs/images/', $contents);
286284
$contents = preg_replace('#href="http://.+?/docs/collection.json"#', 'href="{{ route("apidoc", ["format" => ".json"]) }}"', $contents);
287-
file_put_contents("$outputPath/index.blade.php", $contents);
285+
file_put_contents("$this->outputPath/index.blade.php", $contents);
288286
}
289287
}
290288

291-
/**
292-
* @param string $sourceOutputPath
293-
* @param string $outputPath
294-
* @param bool $isStatic
295-
*/
296-
protected function writeHtmlDocs(string $sourceOutputPath, string $outputPath, bool $isStatic): void
289+
public function writeHtmlDocs(): void
297290
{
298291
$this->output->info('Generating API HTML code');
299292

300-
$this->documentarian->generate($sourceOutputPath);
293+
$this->documentarian->generate($this->sourceOutputPath);
301294

302295
// Move assets to public folder
303-
$this->copyAssetsFromSourceFolderToPublicFolder($sourceOutputPath, $isStatic);
296+
$this->copyAssetsFromSourceFolderToPublicFolder();
304297

305-
$this->moveOutputFromSourceFolderToTargetFolder($sourceOutputPath, $outputPath, $isStatic);
298+
$this->moveOutputFromSourceFolderToTargetFolder();
306299

307-
$this->output->info("Wrote HTML documentation to: {$outputPath}");
300+
$this->output->info("Wrote HTML documentation to: {$this->outputPath}");
308301
}
309302
}

0 commit comments

Comments
 (0)