From 1f1f97235035d8fddcc0b296306d598283fb64bb Mon Sep 17 00:00:00 2001 From: shalvah Date: Sat, 13 Aug 2022 21:19:30 +0200 Subject: [PATCH] Upgrade tool --- README.md | 2 - config/scribe.php | 20 ++++---- src/Commands/GenerateDocumentation.php | 8 +++- src/Commands/Upgrade.php | 66 ++++++++++++++++++-------- 4 files changed, 63 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index c4db5faa..35902b77 100644 --- a/README.md +++ b/README.md @@ -26,8 +26,6 @@ Scribe helps you generate API documentation for humans from your Laravel/Lumen/[ ## Documentation Check out the documentation at [scribe.knuckles.wtf/laravel](http://scribe.knuckles.wtf/laravel). -v2 docs (PHP 7.2+, not actively maintained) are at [scribe.rtfd.io](http://scribe.rtfd.io). - If you're coming from `mpociot/laravel-apidoc-generator`, there's a [migration guide](https://scribe.knuckles.wtf/laravel/migrating-apidoc). ## Contributing diff --git a/config/scribe.php b/config/scribe.php index 0fe1121f..b7cabadd 100644 --- a/config/scribe.php +++ b/config/scribe.php @@ -314,22 +314,22 @@ /* * By default, Scribe will sort groups alphabetically, and endpoints in the order their routes are defined. - * You can customise that by listing the groups, subgroups and endpoints here in the order you want them. + * You can override this by listing the groups, subgroups and endpoints here in the order you want them. * * Any groups, subgroups or endpoints you don't list here will be added as usual after the ones here. - * If an endpoint/subgroups is listed under a group it doesn't belong in, it will be ignored. + * If an endpoint/subgroup is listed under a group it doesn't belong in, it will be ignored. * Note: you must include the initial '/' when writing an endpoint. */ 'order' => [ - // 'This group comes first', - // 'This group comes next' => [ - // 'POST /this-endpoint-comes-first', - // 'GET /this-endpoint-comes-next', + // 'This group will come first', + // 'This group will come next' => [ + // 'POST /this-endpoint-will-comes-first', + // 'GET /this-endpoint-will-comes-next', // ], - // 'This group comes third' => [ - // 'This subgroup comes first' => [ - // 'GET /this-other-endpoint-comes-first', - // 'GET /this-other-endpoint-comes-next', + // 'This group will come third' => [ + // 'This subgroup will come first' => [ + // 'GET /this-other-endpoint-will-comes-first', + // 'GET /this-other-endpoint-will-comes-next', // ] // ] ], diff --git a/src/Commands/GenerateDocumentation.php b/src/Commands/GenerateDocumentation.php index b39eb828..3ef6a71e 100644 --- a/src/Commands/GenerateDocumentation.php +++ b/src/Commands/GenerateDocumentation.php @@ -41,6 +41,12 @@ public function handle(RouteMatcherInterface $routeMatcher, GroupedEndpointsFact { $this->bootstrap(); + if (!empty($this->docConfig->get("default_group"))) { + $this->warn("It looks like you just upgraded to Scribe v4."); + $this->warn("Please run the upgrade command first: `php artisan scribe:upgrade`."); + exit(1); + } + $groupedEndpointsInstance = $groupedEndpointsFactory->make($this, $routeMatcher, $this->configName); $userDefinedEndpoints = Camel::loadUserDefinedEndpoints(Camel::camelDir($this->configName)); @@ -187,7 +193,7 @@ protected function upgradeConfigFileIfNeeded(): void $upgrader = Upgrader::ofConfigFile("config/{$this->configName}.php", __DIR__ . '/../../config/scribe.php') ->dontTouch( 'routes', 'example_languages', 'database_connections_to_transact', 'strategies', 'laravel.middleware', - 'postman.overrides', 'openapi.overrides' + 'postman.overrides', 'openapi.overrides', 'groups' ); $changes = $upgrader->dryRun(); if (!empty($changes)) { diff --git a/src/Commands/Upgrade.php b/src/Commands/Upgrade.php index 7de15249..3cd5414c 100644 --- a/src/Commands/Upgrade.php +++ b/src/Commands/Upgrade.php @@ -7,47 +7,73 @@ class Upgrade extends Command { - protected $signature = "scribe:upgrade {--dry-run}"; + protected $signature = "scribe:upgrade {--dry-run : Print the changes that will be made, without actually making them} + {--config=scribe : choose which config file to use} + "; protected $description = ''; public function handle(): void { - $oldConfig = config('scribe'); - $upgrader = Upgrader::ofConfigFile('config/scribe.php', __DIR__ . '/../../config/scribe.php') + $configName = $this->option('config'); + if (!($oldConfig = config($configName))) { + $this->error("The specified config (config/{$configName}.php) doesn't exist."); + return; + } + + if (array_key_exists("interactive", $oldConfig)) { + $this->error("This upgrade tool is for upgrading from Scribe v3 to v4, but it looks like you're coming from v2."); + $this->error("Please install v3 and follow its upgrade guide first."); + return; + } + + $this->info("Welcome to the Scribe v3 to v4 upgrader."); + $this->line("Checking for config file changes..."); + + $upgrader = Upgrader::ofConfigFile("config/$configName.php", __DIR__ . '/../../config/scribe.php') ->dontTouch('routes', 'laravel.middleware', 'postman.overrides', 'openapi.overrides', 'example_languages', 'database_connections_to_transact', 'strategies') - ->move('interactive', 'try_it_out.enabled') ->move('default_group', 'groups.default') ->move('faker_seed', 'examples.faker_seed'); $changes = $upgrader->dryRun(); if (empty($changes)) { - $this->info("No changes needed! Looks like you're all set."); - return; - } + $this->info("✔ No config file changes needed."); + } else { + $this->info('The following changes will be made to your config file:'); + $this->newLine(); + foreach ($changes as $change) { + $this->line($change["description"]); + } - $this->info('The following changes will be made to your config file:'); - $this->newLine(); - foreach ($changes as $change) { - $this->info($change["description"]); + if (!($this->option('dry-run'))) { + $upgrader->upgrade(); + $this->info("✔ Upgraded your config file. Your old config is backed up at config/$configName.php.bak."); + } } + $this->newLine(); - if ($this->option('dry-run')) { - return; + if ($this->confirm("Do you have any custom strategies?")) { + $this->line('1. Add a new property public ?ExtractedEndpointData $endpointData;.'); + $this->line('2. Replace the array $routeRules parameter in __invoke() with array $routeRules = [] .'); } + $this->newLine(); - $upgrader->upgrade(); + if ($this->confirm("Did you customize the Blade templates used by Scribe?")) { + $this->warn('A few minor changes were made to the templates. See the release announcement for details.'); + } + $this->newLine(); - if (!empty($oldConfig["continue_without_database_transactions"])) { - $this->warn( - '`continue_without_database_transactions` was deprecated in 2.4.0. Your new config file now uses `database_connections_to_transact`.' - ); + $this->line("Scribe now supports PHP 8 attributes for annotations. " + . "You can use both, but we recommend switching to attributes (see the docs)."); + if ($this->confirm("Would you like help in replacing your docblock tags with attributes?")) { + $this->warn('Install our Rector package knuckleswtf/scribe-rector-t2a and run it.'); } + $this->warn("For attributes to work, you need to add the attribute strategies to your config file. See the release announcement for details."); $this->newLine(); - $this->info("✔ Upgraded your config file. Your old config is backed up at config/scribe.php.bak."); - $this->info("Don't forget to check out the changelog or release announcement for new features!"); + $this->info("✔ Done."); + $this->line("See the release announcement at http://scribe.knuckles.wtf/v4 for the full upgrade guide!"); } }