Fix tests

CHANGELOG.md

@@ -13,7 +13,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
+## 1.0.0-alpha1 ()
+### Added
+- Support for closures (https://github.com/mpociot/laravel-apidoc-generator/pull/690)
+
+### Changed
+- Switch from Documentarian to Pastel
+- Switch to Clara for output
+- Split documentation across multiple Markdown files
+- Change behaviour of command. Running `generate` will generate afresh, keeping any changes to MD files. Use --force to discard your changes. Implement new system for tracking and responding to modifications to files; remove update command
+- Added ability to include files by creating arbitrary markdown files
+
+Appearance:
+- Move Postman collection -> TOC footer
+- Change default page title
+- Improve output: use badges, drop tables for paragraphs, style headings
+
+### Fixed
+
+### Removed
+
+
 
 
 
-https://github.com/mpociot/laravel-apidoc-generator/pull/690

composer.json

@@ -35,7 +35,7 @@
         "mpociot/reflection-docblock": "^1.0.1",
         "nunomaduro/collision": "^3.0|^4.0",
         "ramsey/uuid": "^3.8|^4.0",
-        "shalvah/clara": "^2.5",
+        "shalvah/clara": "^2.6",
         "symfony/var-exporter": "^4.0|^5.0"
     },
     "require-dev": {

resources/views/partials/frontmatter.blade.php

@@ -6,10 +6,11 @@ language_tabs:
 @endforeach
 
 includes:
+- "./prepend.md"
 - "./authentication.md"
 - "./groups/*"
 - "./errors.md"
-- "./extra.md"
+- "./append.md"
 
 logo: {{ $settings['logo'] ?? false }}
 

src/Commands/GenerateDocumentation.php

@@ -7,7 +7,7 @@ use Illuminate\Routing\Route;
 use Illuminate\Support\Collection;
 use Illuminate\Support\Facades\URL;
 use Knuckles\Scribe\Extracting\Generator;
-use Knuckles\Scribe\Matching\RouteMatcher\Match;
+use Knuckles\Scribe\Matching\Match;
 use Knuckles\Scribe\Matching\RouteMatcherInterface;
 use Knuckles\Scribe\Tools\DocumentationConfig;
 use Knuckles\Scribe\Tools\Flags;
@@ -63,7 +63,10 @@ class GenerateDocumentation extends Command
         // Using a global static variable here, so fuck off if you don't like it.
         // Also, the --verbose option is included with all Artisan commands.
         Flags::$shouldBeVerbose = $this->option('verbose');
-        $this->clara = clara('knuckleswtf/scribe', Flags::$shouldBeVerbose)->only();
+
+        $this->clara = clara('knuckleswtf/scribe', Flags::$shouldBeVerbose)
+            ->useOutput($this->output)
+            ->only();
 
         $this->docConfig = new DocumentationConfig(config('scribe'));
         $this->baseUrl = $this->docConfig->get('base_url') ?? config('app.url');
@@ -83,7 +86,8 @@ class GenerateDocumentation extends Command
             }, SORT_NATURAL);
         $writer = new Writer(
             $this->docConfig,
-            $this->option('force')
+            $this->option('force'),
+            $this->clara
         );
         $writer->writeDocs($groupedRoutes);
     }

src/Writing/Writer.php

@@ -69,13 +69,13 @@ class Writer
      */
     private $lastTimesWeModifiedTheseFiles;
 
-    public function __construct(DocumentationConfig $config = null, bool $forceIt = false)
+    public function __construct(DocumentationConfig $config = null, bool $forceIt = false, $clara = null)
     {
         // If no config is injected, pull from global
         $this->config = $config ?: new DocumentationConfig(config('scribe'));
         $this->baseUrl = $this->config->get('base_url') ?? config('app.url');
         $this->forceIt = $forceIt;
-        $this->clara = clara('knuckleswtf/scribe', Flags::$shouldBeVerbose)->only();
+        $this->clara = $clara ?: clara('knuckleswtf/scribe', Flags::$shouldBeVerbose)->only();
         $this->shouldGeneratePostmanCollection = $this->config->get('postman.enabled', false);
         $this->pastel = new Pastel();
         $this->isStatic = $this->config->get('type') === 'static';

tests/GenerateDocumentationTest.php

@@ -54,22 +54,34 @@ class GenerateDocumentationTest extends TestCase
     }
 
     /** @test */
-    public function console_command_works_with_closure()
+    public function can_process_traditional_laravel_route_syntax()
+    {
+        RouteFacade::get('/api/test', TestController::class . '@withEndpointDescription');
+
+        config(['scribe.routes.0.match.prefixes' => ['api/*']]);
+        $output = $this->artisan('scribe:generate');
+
+        $this->assertStringContainsString('Processed route: [GET] api/test', $output);
+    }
+
+    /** @test */
+    public function can_process_closure_routes()
     {
         RouteFacade::get('/api/closure', function () {
             return 'hi';
         });
-        RouteFacade::get('/api/test', TestController::class . '@withEndpointDescription');
 
         config(['scribe.routes.0.match.prefixes' => ['api/*']]);
         $output = $this->artisan('scribe:generate');
 
         $this->assertStringContainsString('Processed route: [GET] api/closure', $output);
-        $this->assertStringContainsString('Processed route: [GET] api/test', $output);
     }
 
-    /** @test */
-    public function console_command_works_with_closure_using_dingo()
+    /**
+     * @group dingo
+     * @test
+     */
+    public function can_process_routes_on_dingo()
     {
         $api = app(\Dingo\Api\Routing\Router::class);
         $api->version('v1', function ($api) {
@@ -89,14 +101,13 @@ class GenerateDocumentationTest extends TestCase
     }
 
     /** @test */
-    public function console_command_works_with_routes_callable_tuple()
+    public function can_process__callable_tuple_syntax()
     {
         RouteFacade::get('/api/array/test', [TestController::class, 'withEndpointDescription']);
 
         config(['scribe.routes.0.match.prefixes' => ['api/*']]);
         $output = $this->artisan('scribe:generate');
 
-        $this->assertStringNotContainsString('Skipping route: [GET] api/array/test', $output);
         $this->assertStringContainsString('Processed route: [GET] api/array/test', $output);
     }
 
@@ -137,96 +148,61 @@ class GenerateDocumentationTest extends TestCase
             ],
         ]);
 
-        $this->artisan('scribe:generate');
+        $output = $this->artisan('scribe:generate');
 
-        $fixtureMarkdown = __DIR__ . '/Fixtures/resource_index.md';
-        $generatedMarkdown = __DIR__ . '/../resources/docs/source/index.md';
-        $this->assertFilesHaveSameContent($fixtureMarkdown, $generatedMarkdown);
+        $this->assertStringContainsString('Processed route: [GET] api/users', $output);
+        $this->assertStringContainsString('Processed route: [GET] api/users/create', $output);
+        $this->assertStringContainsString('Processed route: [GET] api/users/{user}', $output);
+        $this->assertStringContainsString('Processed route: [GET] api/users/{user}/edit', $output);
+        $this->assertStringContainsString('Processed route: [POST] api/users', $output);
+        $this->assertStringContainsString('Processed route: [PUT,PATCH] api/users/{user}', $output);
+        $this->assertStringContainsString('Processed route: [DELETE] api/users/{user}', $output);
     }
 
     /** @test */
     public function can_parse_partial_resource_routes()
     {
         RouteFacade::resource('/api/users', TestResourceController::class)
-                ->only(['index', 'create']);
+                ->only(['index', 'store']);
 
-        config(['apidoc.routes.0.match.prefixes' => ['api/*']]);
+        config(['scribe.routes.0.match.prefixes' => ['api/*']]);
         config([
-            'apidoc.routes.0.apply.headers' => [
+            'scribe.routes.0.apply.headers' => [
                 'Accept' => 'application/json',
             ],
         ]);
 
-        $this->artisan('apidoc:generate');
-
-        $fixtureMarkdown = __DIR__ . '/Fixtures/partial_resource_index.md';
-        $generatedMarkdown = __DIR__ . '/../resources/docs/source/index.md';
-        $this->assertFilesHaveSameContent($fixtureMarkdown, $generatedMarkdown);
-
-        RouteFacade::apiResource('/api/users', TestResourceController::class)
-                ->only(['index', 'create']);
+        $output = $this->artisan('scribe:generate');
 
-        $this->artisan('apidoc:generate');
+        $this->assertStringContainsString('Processed route: [GET] api/users', $output);
+        $this->assertStringContainsString('Processed route: [POST] api/users', $output);
 
-        $fixtureMarkdown = __DIR__ . '/Fixtures/partial_resource_index.md';
-        $generatedMarkdown = __DIR__ . '/../resources/docs/source/index.md';
-        $this->assertFilesHaveSameContent($fixtureMarkdown, $generatedMarkdown);
-    }
-
-    /** @test */
-    public function generated_markdown_file_is_correct()
-    {
-        RouteFacade::get('/api/withDescription', [TestController::class, 'withEndpointDescription']);
-        RouteFacade::get('/api/withResponseTag', TestController::class . '@withResponseTag');
-        RouteFacade::get('/api/withBodyParameters', TestController::class . '@withBodyParameters');
-        RouteFacade::get('/api/withQueryParameters', TestController::class . '@withQueryParameters');
-        RouteFacade::get('/api/withAuthTag', TestController::class . '@withAuthenticatedTag');
-        RouteFacade::get('/api/withEloquentApiResource', [TestController::class, 'withEloquentApiResource']);
-        RouteFacade::get('/api/withEloquentApiResourceCollectionClass', [TestController::class, 'withEloquentApiResourceCollectionClass']);
-        RouteFacade::post('/api/withMultipleResponseTagsAndStatusCode', [TestController::class, 'withMultipleResponseTagsAndStatusCode']);
-        RouteFacade::get('/api/echoesUrlParameters/{param}-{param2}/{param3?}', [TestController::class, 'echoesUrlParameters']);
+        $this->assertStringNotContainsString('Processed route: [PUT,PATCH] api/users/{user}', $output);
+        $this->assertStringNotContainsString('Processed route: [DELETE] api/users/{user}', $output);
 
-        // We want to have the same values for params each time
-        config(['apidoc.type' => 'static']);
-        config(['apidoc.faker_seed' => 1234]);
-        config(['apidoc.routes.0.match.prefixes' => ['api/*']]);
-        config([
-            'apidoc.routes.0.apply.headers' => [
-                'Authorization' => 'customAuthToken',
-                'Custom-Header' => 'NotSoCustom',
-                'Content-Type' => 'application/json',
-                'Accept' => 'application/json',
-            ],
-        ]);
-        $this->artisan('apidoc:generate');
+        RouteFacade::apiResource('/api/users', TestResourceController::class)
+                ->only(['index', 'store']);
+        $output = $this->artisan('scribe:generate');
 
-        $generatedMarkdown = __DIR__ . '/../resources/docs/source/index.md';
-        $compareMarkdown = __DIR__ . '/../resources/docs/source/.compare.md';
-        $fixtureMarkdown = __DIR__ . '/Fixtures/index.md';
+        $this->assertStringContainsString('Processed route: [GET] api/users', $output);
+        $this->assertStringContainsString('Processed route: [POST] api/users', $output);
 
-        $this->assertFilesHaveSameContent($fixtureMarkdown, $generatedMarkdown);
-        $this->assertFilesHaveSameContent($fixtureMarkdown, $compareMarkdown);
+        $this->assertStringNotContainsString('Processed route: [PUT,PATCH] api/users/{user}', $output);
+        $this->assertStringNotContainsString('Processed route: [DELETE] api/users/{user}', $output);
     }
 
     /** @test */
-    public function can_prepend_and_append_data_to_generated_markdown()
+    public function supports_partial_resource_controller()
     {
-        RouteFacade::get('/api/test', TestController::class . '@withEndpointDescription');
-        RouteFacade::get('/api/responseTag', TestController::class . '@withResponseTag');
+        RouteFacade::resource('/api/users', TestPartialResourceController::class);
 
-        config(['apidoc.routes.0.match.prefixes' => ['api/*']]);
-        $this->artisan('apidoc:generate');
+        config(['scribe.routes.0.prefixes' => ['api/*']]);
 
-        $prependMarkdown = __DIR__ . '/Fixtures/prepend.md';
-        $appendMarkdown = __DIR__ . '/Fixtures/append.md';
-        copy($prependMarkdown, __DIR__ . '/../resources/docs/source/prepend.md');
-        copy($appendMarkdown, __DIR__ . '/../resources/docs/source/append.md');
+        $output = $this->artisan('scribe:generate');
 
-        $this->artisan('apidoc:generate');
+        $this->assertStringContainsString('Processed route: [GET] api/users', $output);
+        $this->assertStringContainsString('Processed route: [PUT,PATCH] api/users/{user}', $output);
 
-        $generatedMarkdown = __DIR__ . '/../resources/docs/source/index.md';
-        $this->assertContainsIgnoringWhitespace($this->getFileContents($prependMarkdown), $this->getFileContents($generatedMarkdown));
-        $this->assertContainsIgnoringWhitespace($this->getFileContents($appendMarkdown), $this->getFileContents($generatedMarkdown));
     }
 
     /** @test */
@@ -243,10 +219,10 @@ class GenerateDocumentationTest extends TestCase
         RouteFacade::get('/api/echoesUrlParameters/{param}-{param2}/{param3?}', [TestController::class, 'echoesUrlParameters']);
 
         // We want to have the same values for params each time
-        config(['apidoc.faker_seed' => 1234]);
-        config(['apidoc.routes.0.match.prefixes' => ['api/*']]);
+        config(['scribe.faker_seed' => 1234]);
+        config(['scribe.routes.0.match.prefixes' => ['api/*']]);
         config([
-            'apidoc.routes.0.apply.headers' => [
+            'scribe.routes.0.apply.headers' => [
                 'Authorization' => 'customAuthToken',
                 'Custom-Header' => 'NotSoCustom',
                 'Accept' => 'application/json',
@@ -254,7 +230,7 @@ class GenerateDocumentationTest extends TestCase
             ],
         ]);
 
-        $this->artisan('apidoc:generate');
+        $this->artisan('scribe:generate');
 
         $generatedCollection = json_decode(file_get_contents(__DIR__ . '/../public/docs/collection.json'), true);
         // The Postman ID varies from call to call; erase it to make the test data reproducible.
@@ -269,9 +245,9 @@ class GenerateDocumentationTest extends TestCase
         $domain = 'http://somedomain.test';
         RouteFacade::get('/api/test', TestController::class . '@withEndpointDescription');
 
-        config(['apidoc.base_url' => $domain]);
-        config(['apidoc.routes.0.match.prefixes' => ['api/*']]);
-        $this->artisan('apidoc:generate');
+        config(['scribe.base_url' => $domain]);
+        config(['scribe.routes.0.match.prefixes' => ['api/*']]);
+        $this->artisan('scribe:generate');
 
         $generatedCollection = json_decode(file_get_contents(__DIR__ . '/../public/docs/collection.json'));
         $endpointUrl = $generatedCollection->item[0]->item[0]->request->url->host;
@@ -281,12 +257,12 @@ class GenerateDocumentationTest extends TestCase
     /** @test */
     public function generated_postman_collection_can_have_custom_url()
     {
-        Config::set('apidoc.base_url', 'http://yourapp.app');
+        Config::set('scribe.base_url', 'http://yourapp.app');
         RouteFacade::get('/api/test', TestController::class . '@withEndpointDescription');
         RouteFacade::post('/api/responseTag', TestController::class . '@withResponseTag');
 
-        config(['apidoc.routes.0.match.prefixes' => ['api/*']]);
-        $this->artisan('apidoc:generate');
+        config(['scribe.routes.0.match.prefixes' => ['api/*']]);
+        $this->artisan('scribe:generate');
 
         $generatedCollection = json_decode(file_get_contents(__DIR__ . '/../public/docs/collection.json'), true);
         // The Postman ID varies from call to call; erase it to make the test data reproducible.
@@ -298,12 +274,12 @@ class GenerateDocumentationTest extends TestCase
     /** @test */
     public function generated_postman_collection_can_have_secure_url()
     {
-        Config::set('apidoc.base_url', 'https://yourapp.app');
+        Config::set('scribe.base_url', 'https://yourapp.app');
         RouteFacade::get('/api/test', TestController::class . '@withEndpointDescription');
         RouteFacade::post('/api/responseTag', TestController::class . '@withResponseTag');
 
-        config(['apidoc.routes.0.match.prefixes' => ['api/*']]);
-        $this->artisan('apidoc:generate');
+        config(['scribe.routes.0.match.prefixes' => ['api/*']]);
+        $this->artisan('scribe:generate');
 
         $generatedCollection = json_decode(file_get_contents(__DIR__ . '/../public/docs/collection.json'), true);
         // The Postman ID varies from call to call; erase it to make the test data reproducible.
@@ -316,14 +292,14 @@ class GenerateDocumentationTest extends TestCase
     public function generated_postman_collection_can_append_custom_http_headers()
     {
         RouteFacade::get('/api/headers', TestController::class . '@checkCustomHeaders');
-        config(['apidoc.routes.0.match.prefixes' => ['api/*']]);
+        config(['scribe.routes.0.match.prefixes' => ['api/*']]);
         config([
-            'apidoc.routes.0.apply.headers' => [
+            'scribe.routes.0.apply.headers' => [
                 'Authorization' => 'customAuthToken',
                 'Custom-Header' => 'NotSoCustom',
             ],
         ]);
-        $this->artisan('apidoc:generate');
+        $this->artisan('scribe:generate');
 
         $generatedCollection = json_decode(file_get_contents(__DIR__ . '/../public/docs/collection.json'), true);
         // The Postman ID varies from call to call; erase it to make the test data reproducible.
@@ -337,9 +313,9 @@ class GenerateDocumentationTest extends TestCase
     {
         RouteFacade::get('/api/withQueryParameters', TestController::class . '@withQueryParameters');
         // We want to have the same values for params each time
-        config(['apidoc.faker_seed' => 1234]);
-        config(['apidoc.routes.0.match.prefixes' => ['api/*']]);
-        $this->artisan('apidoc:generate');
+        config(['scribe.faker_seed' => 1234]);
+        config(['scribe.routes.0.match.prefixes' => ['api/*']]);
+        $this->artisan('scribe:generate');
 
         $generatedCollection = json_decode(file_get_contents(__DIR__ . '/../public/docs/collection.json'), true);
         // The Postman ID varies from call to call; erase it to make the test data reproducible.
@@ -353,9 +329,9 @@ class GenerateDocumentationTest extends TestCase
     {
         RouteFacade::get('/api/withBodyParameters', TestController::class . '@withBodyParameters');
         // We want to have the same values for params each time
-        config(['apidoc.faker_seed' => 1234]);
-        config(['apidoc.routes.0.match.prefixes' => ['api/*']]);
-        $this->artisan('apidoc:generate');
+        config(['scribe.faker_seed' => 1234]);
+        config(['scribe.routes.0.match.prefixes' => ['api/*']]);
+        $this->artisan('scribe:generate');
 
         $generatedCollection = json_decode(file_get_contents(__DIR__ . '/../public/docs/collection.json'), true);
         // The Postman ID varies from call to call; erase it to make the test data reproducible.
@@ -369,16 +345,16 @@ class GenerateDocumentationTest extends TestCase
     {
         RouteFacade::get('/api/headers', TestController::class . '@checkCustomHeaders');
 
-        config(['apidoc.routes.0.match.prefixes' => ['api/*']]);
+        config(['scribe.routes.0.match.prefixes' => ['api/*']]);
         config([
-            'apidoc.routes.0.apply.headers' => [
+            'scribe.routes.0.apply.headers' => [
                 'Authorization' => 'customAuthToken',
                 'Custom-Header' => 'NotSoCustom',
             ],
         ]);
-        $this->artisan('apidoc:generate');
+        $this->artisan('scribe:generate');
 
-        $generatedMarkdown = $this->getFileContents(__DIR__ . '/../resources/docs/source/index.md');
+        $generatedMarkdown = $this->getFileContents(__DIR__ . '/../resources/docs/source/groups/0-group-a.md');
         $this->assertContainsIgnoringWhitespace('"Authorization": "customAuthToken","Custom-Header":"NotSoCustom"', $generatedMarkdown);
     }
 
@@ -387,10 +363,10 @@ class GenerateDocumentationTest extends TestCase
     {
         RouteFacade::get('/api/utf8', TestController::class . '@withUtf8ResponseTag');
 
-        config(['apidoc.routes.0.prefixes' => ['api/*']]);
-        $this->artisan('apidoc:generate');
+        config(['scribe.routes.0.prefixes' => ['api/*']]);
+        $this->artisan('scribe:generate');
 
-        $generatedMarkdown = file_get_contents(__DIR__ . '/../resources/docs/source/index.md');
+        $generatedMarkdown = file_get_contents(__DIR__ . '/../resources/docs/source/groups/0-group-a.md');
         $this->assertStringContainsString('Лорем ипсум долор сит амет', $generatedMarkdown);
     }
 
@@ -402,41 +378,11 @@ class GenerateDocumentationTest extends TestCase
         RouteFacade::get('/api/action2', TestGroupController::class . '@action2');
         RouteFacade::get('/api/action10', TestGroupController::class . '@action10');
 
-        config(['apidoc.routes.0.prefixes' => ['api/*']]);
-        $this->artisan('apidoc:generate');
-        $generatedMarkdown = file_get_contents(__DIR__ . '/../resources/docs/source/index.md');
-
-        $firstGroup1Occurrence = strpos($generatedMarkdown, '#1. Group 1');
-        $firstGroup2Occurrence = strpos($generatedMarkdown, '#2. Group 2');
-        $firstGroup10Occurrence = strpos($generatedMarkdown, '#10. Group 10');
-
-        $this->assertNotFalse($firstGroup1Occurrence);
-        $this->assertNotFalse($firstGroup2Occurrence);
-        $this->assertNotFalse($firstGroup2Occurrence);
-
-        $this->assertTrue(
-            $firstGroup1Occurrence < $firstGroup2Occurrence && $firstGroup2Occurrence < $firstGroup10Occurrence
-        );
-    }
-
-    /** @test */
-    public function supports_partial_resource_controller()
-    {
-        RouteFacade::resource('/api/partial', TestPartialResourceController::class);
-
-        config(['apidoc.routes.0.prefixes' => ['api/*']]);
-
-        $thrownException = null;
-
-        try {
-            $this->artisan('apidoc:generate');
-        } catch (ReflectionException $e) {
-            $thrownException = $e;
-        }
+        config(['scribe.routes.0.prefixes' => ['api/*']]);
+        $this->artisan('scribe:generate');
 
-        $this->assertNull($thrownException);
-        $generatedMarkdown = file_get_contents(__DIR__ . '/../resources/docs/source/index.md');
-        $this->assertStringContainsString('Group A', $generatedMarkdown);
-        $this->assertStringContainsString('Group B', $generatedMarkdown);
+        $this->assertFileExists(__DIR__ . '/../resources/docs/source/groups/0-1-group-1.md');
+        $this->assertFileExists(__DIR__ . '/../resources/docs/source/groups/1-2-group-2.md');
+        $this->assertFileExists(__DIR__ . '/../resources/docs/source/groups/2-10-group-10.md');
     }
 }

tests/Unit/GeneratorTestCase.php

@@ -620,7 +620,7 @@ abstract class GeneratorTestCase extends TestCase
      */
     public function can_parse_transformer_tag($serializer, $expected)
     {
-        config(['apidoc.fractal.serializer' => $serializer]);
+        config(['scribe.fractal.serializer' => $serializer]);
         $route = $this->createRoute('GET', '/transformerTag', 'transformerTag');
         $parsed = $this->generator->processRoute($route);
         $response = Arr::first($parsed['responses']);