From 0d3df3ac45ef744d28b507d12cb267f19749bf6c Mon Sep 17 00:00:00 2001 From: shalvah Date: Fri, 8 May 2020 13:11:24 +0100 Subject: [PATCH] Refactor Laravel type to use /docs for routing by default, rather than /doc. --- config/scribe.php | 4 ++-- docs/config.md | 6 ++---- docs/guide-getting-started.md | 4 ++-- routes/laravel.php | 2 +- src/Tools/Utils.php | 4 ++-- src/Writing/Writer.php | 13 +++++++++---- todo.md | 1 - 7 files changed, 18 insertions(+), 16 deletions(-) diff --git a/config/scribe.php b/config/scribe.php index faa1ce5c..48019e29 100644 --- a/config/scribe.php +++ b/config/scribe.php @@ -20,9 +20,9 @@ /* * URL path to use for the docs endpoint (if `add_routes` is true). - * By default, `/doc` opens the HTML page, and `/doc.json` downloads the Postman collection. + * By default, `/docs` opens the HTML page, and `/docs.json` downloads the Postman collection. */ - 'url' => '/doc', + 'url' => '/docs', /* * Middleware to attach to the docs endpoint (if `add_routes` is true). diff --git a/docs/config.md b/docs/config.md index f6fb1936..d054bb3e 100644 --- a/docs/config.md +++ b/docs/config.md @@ -16,9 +16,7 @@ If you're using `laravel` type output, this package can automatically set up an Set this to `true` if you want the documentation endpoint to be automatically set up for you. Of course, you can use your own routing instead, by setting this to `false`. ### `docs_url` -The path for the documentation endpoint (if `add_routes` is true). Your Postman collection (if you have that enabled) will be at this path + '.json' (eg `/doc.json`). Default: `/doc` - -> Note: There is currently a known issue with using `/docs` as the path for `laravel` docs. You should not use it, as it conflicts with the folder structure in the `public` folder and may confuse the webserver. +The path for the documentation endpoint (if `add_routes` is true). Your Postman collection (if you have that enabled) will be at this path + '.json' (eg `/docs.json`). Default: `/docs` ### `middleware` Here, you can specify middleware to be attached to the documentation endpoint (if `add_routes` is true). @@ -32,7 +30,7 @@ The base URL to be used in examples and the Postman collection. By default, this ## `postman` This package can automatically generate a Postman collection for your routes, along with the documentation. This section is where you can configure (or disable) that. - For `static` docs (see [type](#type)), the collection will be created in `public/docs/collection.json`, so it can be accessed by visiting {yourapp.domain}/docs/colllection.json. -- For `laravel` docs, the collection will be generated to `storage/app/scribe/collection.json`. Setting `laravel.add_routes` to true will add a `/doc.json` endpoint to fetch it.. +- For `laravel` docs, the collection will be generated to `storage/app/scribe/collection.json`. Setting `laravel.add_routes` to true will add a `/docs.json` endpoint to fetch it.. ### `enabled` Whether or not to generate a Postman API collection. Default: **true** diff --git a/docs/guide-getting-started.md b/docs/guide-getting-started.md index 483debab..2382772a 100644 --- a/docs/guide-getting-started.md +++ b/docs/guide-getting-started.md @@ -79,9 +79,9 @@ Now, let's do a test run. Run the command to generate your docs. php artisan scribe:generate ``` -Open up your docs in your browser. If you're using `static` type, just find the `docs/index.html` file in your public/ folder. If you're using `laravel` type, start your app (`php artisan serve`), then visit `/doc`. You should see your docs show up nicely. +Open up your docs in your browser. If you're using `static` type, just find the `docs/index.html` file in your public/ folder. If you're using `laravel` type, start your app (`php artisan serve`), then visit `/docs`. You should see your docs show up nicely. -There's also a Postman collection generated for you by default. You can get it by visiting `/docs/collection.json` for `static` type, and `/doc.json` for `laravel` type. +There's also a Postman collection generated for you by default. You can get it by visiting `/docs/collection.json` for `static` type, and `/docs.json` for `laravel` type. ## Add information about your API Now you can add more detail to your documentation. Here are some things you can customise: diff --git a/routes/laravel.php b/routes/laravel.php index 1306d288..0e2ab39f 100644 --- a/routes/laravel.php +++ b/routes/laravel.php @@ -2,7 +2,7 @@ use Illuminate\Support\Facades\Route; -$prefix = config('scribe.laravel.docs_url', '/doc'); +$prefix = config('scribe.laravel.docs_url', '/docs'); $middleware = config('scribe.laravel.middleware', []); Route::namespace('\Knuckles\Scribe\Http') diff --git a/src/Tools/Utils.php b/src/Tools/Utils.php index ad7f93d4..1d658915 100644 --- a/src/Tools/Utils.php +++ b/src/Tools/Utils.php @@ -101,10 +101,10 @@ public static function dumpException(Exception $e) } } - public static function deleteDirectoryAndContents($dir) + public static function deleteDirectoryAndContents($dir, $base = null) { $dir = ltrim($dir, '/'); - $adapter = new Local(realpath(__DIR__ . '/../../')); + $adapter = new Local($base ?: realpath(__DIR__ . '/../../')); $fs = new Filesystem($adapter); $fs->deleteDir($dir); } diff --git a/src/Writing/Writer.php b/src/Writing/Writer.php index 5fad6584..b4f8a25e 100644 --- a/src/Writing/Writer.php +++ b/src/Writing/Writer.php @@ -10,6 +10,7 @@ use Knuckles\Pastel\Pastel; use Knuckles\Scribe\Tools\DocumentationConfig; use Knuckles\Scribe\Tools\Flags; +use Knuckles\Scribe\Tools\Utils; use Shalvah\Clara\Clara; class Writer @@ -194,14 +195,18 @@ protected function performFinalTasksForLaravelType(): void if (!is_dir($this->outputPath)) { mkdir($this->outputPath); } + rename("public/docs/index.html", "$this->outputPath/index.blade.php"); + // Move assets from public/docs to public/vendor/scribe + Utils::deleteDirectoryAndContents("public/vendor/scribe/", getcwd()); + rename("public/docs/", "public/vendor/scribe/"); + $contents = file_get_contents("$this->outputPath/index.blade.php"); // Rewrite links to go through Laravel - $contents = str_replace('href="css/style.css"', 'href="/docs/css/style.css"', $contents); - $contents = str_replace('src="js/all.js"', 'src="/docs/js/all.js"', $contents); - $contents = str_replace('src="images/', 'src="/docs/images/', $contents); - $contents = preg_replace('#href="./collection.json"#', 'href="{{ route("scribe.json") }}"', $contents); + $contents = preg_replace('#href="css/(.+?)"#', 'href="{{ asset("vendor/scribe/css/$1") }}"', $contents); + $contents = preg_replace('#src="(js|images)/(.+?)"#', 'src="{{ asset("vendor/scribe/$1/$2") }}"', $contents); + $contents = str_replace('href="./collection.json"', 'href="{{ route("scribe.json") }}"', $contents); file_put_contents("$this->outputPath/index.blade.php", $contents); } diff --git a/todo.md b/todo.md index 260ce283..7ff65fd1 100644 --- a/todo.md +++ b/todo.md @@ -18,7 +18,6 @@ - Possible feature: https://github.com/mpociot/laravel-apidoc-generator/issues/731 # Improvements -- Find out a way to make automatic routing for Laravel work with /docs instead of /doc - Improve error messaging: there's lots of places where it can crash because of wrong user input. We can try to have more descriptive error messages. # Tests