Rename config key from laravel.autoload to laravel.add_routes

config/scribe.php

@@ -4,8 +4,7 @@ return [
     /*
      * The type of documentation output to generate.
      * - "static" will generate a static HTMl page in the /public/docs folder,
-     * - "laravel" will generate the documentation as a Blade view,
-     * so you can add routing and authentication.
+     * - "laravel" will generate the documentation as a Blade view, so you can add routing and authentication.
      */
     'type' => 'static',
 
@@ -17,25 +16,32 @@ return [
          * Whether to automatically create a docs endpoint for you to view your generated docs.
          * If this is false, you can still set up routing manually.
          */
-        'autoload' => false,
+        'add_routes' => true,
 
         /*
-         * URL path to use for the docs endpoint (if `autoload` is true).
-         *
+         * 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.
          */
-        'docs_url' => '/doc',
+        'url' => '/doc',
 
         /*
-         * Middleware to attach to the docs endpoint (if `autoload` is true).
+         * Middleware to attach to the docs endpoint (if `add_routes` is true).
          */
         'middleware' => [],
     ],
 
     /*
-     * The router to be used (Laravel or Dingo).
+     * Example requests for each endpoint will be shown in each of these languages.
+     * Supported options are: bash, javascript, php, python
+     * You can add a language of your own, but you must publish the package's views
+     * and define a corresponding view for it in the partials/example-requests directory.
+     * See https://scribe.readthedocs.io/en/latest/generating-documentation.html
+     *
      */
-    'router' => 'laravel',
+    'example_languages' => [
+        'bash',
+        'javascript',
+    ],
 
     /*
      * The base URL to be used in examples and the Postman collection.
@@ -72,10 +78,32 @@ return [
         'auth' => null,
     ],
 
+    /*
+     * Name for the group of routes which do not have a @group set.
+     */
+    'default_group' => 'Endpoints',
+
+    /*
+     * Custom logo path. The will be used as the value of the src attribute for the <img> tag,
+     * so make sure it points to a public URL or path accessible from your web server. For best results the image width should be 230px.
+     * Set this to false to not use a logo.
+     *
+     * For example, if your logo is in public/img:
+     * - 'logo' => '../img/logo.png' // for `static` type (output folder is public/docs)
+     * - 'logo' => 'img/logo.png' // for `laravel` type
+     *
+     */
+    'logo' => false,
+
+    /*
+     * The router your API is using (Laravel or Dingo).
+     */
+    'router' => 'laravel',
+
     /*
      * The routes for which documentation should be generated.
      * Each group contains rules defining which routes should be included ('match', 'include' and 'exclude' sections)
-     * and rules which should be applied to them ('apply' section).
+     * and settings which should be applied to them ('apply' section).
      */
     'routes' => [
         [
@@ -84,48 +112,37 @@ return [
              * A route must fulfill ALL conditions to pass.
              */
             'match' => [
-
                 /*
-                 * Match only routes whose domains match this pattern (use * as a wildcard to match any characters).
+                 * Match only routes whose domains match this pattern (use * as a wildcard to match any characters). Example: 'api.*'.
                  */
-                'domains' => [
-                    '*',
-                    // 'domain1.*',
-                ],
+                'domains' => ['*'],
 
                 /*
-                 * Match only routes whose paths match this pattern (use * as a wildcard to match any characters).
+                 * Match only routes whose paths match this pattern (use * as a wildcard to match any characters). Example: 'users/*'.
                  */
-                'prefixes' => [
-                    '*',
-                    // 'users/*',
-                ],
+                'prefixes' => ['*'],
 
                 /*
-                 * Match only routes registered under this version. This option is ignored for Laravel router.
+                 * (Dingo router only) Match only routes registered under this version.
                  * Note that wildcards are not supported.
                  */
-                'versions' => [
-                    'v1',
-                ],
+                'versions' => ['v1'],
             ],
 
             /*
-             * Include these routes when generating documentation,
-             * even if they did not match the rules above.
-             * Note that the route must be referenced by name here (wildcards are supported).
+             * Include these routes when generating documentation, even if they did not match the rules above.
+             * The route can be referenced by name or path here. Wildcards are supported.
              */
             'include' => [
                 // 'users.index', 'healthcheck*'
             ],
 
             /*
-             * Exclude these routes when generating documentation,
-             * even if they matched the rules above.
-             * Note that the route must be referenced by name here (wildcards are supported).
+             * Exclude these routes when generating documentation, even if they matched the rules above.
+             * The route can be referenced by name or path here. Wildcards are supported.
              */
             'exclude' => [
-                // 'users.create', 'admin.*'
+                // '/health', 'admin.*'
             ],
 
             /*
@@ -191,6 +208,23 @@ return [
         ],
     ],
 
+    /*
+     * Configure how responses are transformed using @transformer and @transformerCollection (requires league/fractal package)
+     */
+    'fractal' => [
+        /* If you are using a custom serializer with league/fractal, you can specify it here.
+         * Leave as null to use no serializer or return simple JSON.
+         */
+        'serializer' => null,
+    ],
+
+    /*
+     * If you would like the package to generate the same example values for parameters on each run,
+     * set this to any number (eg. 1234)
+     *
+     */
+    'faker_seed' => null,
+
     'strategies' => [
         'metadata' => [
             \Knuckles\Scribe\Extracting\Strategies\Metadata\GetFromDocBlocks::class,
@@ -220,64 +254,7 @@ return [
     ],
 
     /*
-     * Custom logo path. The will be used as the value of the src attribute for the <img> tag,
-     * so make sure it points to a public URL or path accessible from your web server.
-     * Set this to false to not use a logo.
-     *
-     * For example, if your logo is in public/img:
-     * - 'logo' => 'img/logo.png' // for `laravel` type
-     * - 'logo' => '../img/logo.png' // for `static` type (output folder is public/docs)
-     *
-     * For best results the image width should be 230px.
-     */
-    'logo' => false,
-
-    /*
-     * Name for the group of routes which do not have a @group set.
-     */
-    'default_group' => 'general',
-
-    /*
-     * Example requests for each endpoint will be shown in each of these languages.
-     * Supported options are: bash, javascript, php, python
-     * You can add a language of your own, but you must publish the package's views
-     * and define a corresponding view for it in the partials/example-requests directory.
-     * See https://scribe.readthedocs.io/en/latest/generating-documentation.html
-     *
-     */
-    'example_languages' => [
-        'bash',
-        'javascript',
-    ],
-
-    /*
-     * Configure how responses are transformed using @transformer and @transformerCollection
-     * Requires league/fractal package: composer require league/fractal
-     *
-     */
-    'fractal' => [
-        /* If you are using a custom serializer with league/fractal,
-         * you can specify it here.
-         *
-         * Serializers included with league/fractal:
-         * - \League\Fractal\Serializer\ArraySerializer::class
-         * - \League\Fractal\Serializer\DataArraySerializer::class
-         * - \League\Fractal\Serializer\JsonApiSerializer::class
-         *
-         * Leave as null to use no serializer or return a simple JSON.
-         */
-        'serializer' => null,
-    ],
-
-    /*
-     * If you would like the package to generate the same example values for parameters on each run,
-     * set this to any number (eg. 1234)
-     *
-     */
-    'faker_seed' => null,
-
-    /*
-     * If you would like to customize how routes are matched beyond the route configuration you may
+     * [Advanced usage] If you would like to customize how routes are matched beyond the route configuration you may
      * declare your own implementation of RouteMatcherInterface
      *
      */

docs/config.md

@@ -12,18 +12,16 @@ This is the type of documentation output to generate.
 ## `laravel`
 If you're using `laravel` type output, this package can automatically set up an endpoint for you to view your generated docs. You can configure this here.
 
-### `autoload`
-Set this to `true` if you want the documentation endpoint to be automatically set up for you. Default: `false` (*note that this will change in the next major release*)
-
-You may, of course, use your own routing instead of using `autoload`.
+### `add_routes`
+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 `autoload` is true). Your Postman collection (if you have that enabled) will be at this path + '.json' (eg `/doc.json`). Default: `/doc`
+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.
 
 ### `middleware`
-Here, you can specify middleware to be attached to the documentation endpoint (if `autoload` is true).
+Here, you can specify middleware to be attached to the documentation endpoint (if `add_routes` is true).
 
 ## `router`
 The router to use when processing your routes (can be Laravel or Dingo. Defaults to **Laravel**)
@@ -34,7 +32,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.autoload` to true will add a `/docs.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 `/doc.json` endpoint to fetch it..
 
 ### `enabled`
 Whether or not to generate a Postman API collection. Default: **true**

src/Extracting/Strategies/Responses/UseApiResourceTags.php

@@ -128,7 +128,7 @@ class UseApiResourceTags extends Strategy
         $states = [];
         if ($modelTag) {
             ['content' => $type, 'attributes' => $attributes] = AnnotationParser::parseIntoContentAndAttributes($modelTag->getContent(), ['states']);
-            $states = explode(',', $attributes['states'] ?? '');
+            $states = $attributes['states'] ? explode(',', $attributes['states']) : [];
         }
 
         if (empty($type)) {

src/Extracting/Strategies/Responses/UseTransformerTags.php

@@ -130,7 +130,7 @@ class UseTransformerTags extends Strategy
         $states = [];
         if ($modelTag) {
             ['content' => $type, 'attributes' => $attributes] = AnnotationParser::parseIntoContentAndAttributes($modelTag->getContent(), ['states']);
-            $states = explode(',', $attributes['states'] ?? '');
+            $states = $attributes['states'] ? explode(',', $attributes['states']) : [];
         } else {
             $parameter = Arr::first($transformerMethod->getParameters());
             if ($parameter->hasType() && ! $parameter->getType()->isBuiltin() && class_exists($parameter->getType()->getName())) {

src/ScribeServiceProvider.php

@@ -47,7 +47,7 @@ class ScribeServiceProvider extends ServiceProvider
     {
         if (
             config('scribe.type', 'static') === 'laravel' &&
-            config('scribe.laravel.autoload', false)
+            config('scribe.laravel.add_routes', false)
         ) {
             $this->loadRoutesFrom(
                 __DIR__ . '/../routes/laravel.php'

src/Tools/AnnotationParser.php

@@ -25,7 +25,7 @@ class AnnotationParser
      */
     public static function parseIntoContentAndAttributes(string $annotationContent, array $allowedAttributes): array
     {
-        $result = preg_split('/(\w+)=([\S]+|".+?"|\'.+?\')\s*/', trim($annotationContent), -1, PREG_SPLIT_DELIM_CAPTURE | PREG_SPLIT_NO_EMPTY);
+        $result = preg_split('/(\w+)=([^\s\'"]+|".+?"|\'.+?\')\s*/', trim($annotationContent), -1, PREG_SPLIT_DELIM_CAPTURE | PREG_SPLIT_NO_EMPTY);
 
         $defaults = array_fill_keys($allowedAttributes, null);
         if (count($result) == 1) { // No key-value pairs

tests/Fixtures/TestUserApiResource.php

@@ -15,12 +15,17 @@ class TestUserApiResource extends JsonResource
      */
     public function toArray($request)
     {
-        return [
+        $result = [
             'id' => $this->id,
             'name' => $this->first_name . ' ' . $this->last_name,
             'email' => $this->email,
-            'state1' => $this['state1'],
-            'random-state' => $this['random-state'],
         ];
+
+        if ($this['state1'] && $this['random-state']) {
+            $result['state1'] = $this['state1'];
+            $result['random-state'] = $this['random-state'];
+        }
+
+        return $result;
     }
 }