docs

config/scramble.php

@@ -3,11 +3,20 @@
 use Dedoc\Scramble\Http\Middleware\RestrictedDocsAccess;
 
 return [
-    'base_url' => url('/api'),
+    /*
+     * Your API server base URL: will be used as base URL in docs.
+     */
+    'api_base_url' => url('/api'),
 
     'info' => [
+        /*
+         * API version.
+         */
         'version' => env('API_VERSION', '0.0.1'),
 
+        /*
+         * Description rendered on the home page of the API documentation (`/docs/api`).
+         */
         'description' => '',
     ],
 

docs/installation.md

@@ -33,4 +33,4 @@ Optionally, you can publish package's config file:
 php artisan vendor:publish --provider="Dedoc\Scramble\ScrambleServiceProvider" --tag="scramble-config"
 ```
 
-This will allow you to add custom extensions.
+This will allow you to customize the OpenAPI document info and add custom extensions.

docs/usage/info.md

@@ -0,0 +1,46 @@
+---
+title: Documentation config
+weight: 5
+---
+
+Scramble allows to customize API base URL and OpenAPI document's `info` block by publishing a config file.
+
+`info` block includes API version and API description. API description is rendered on the home page (`/docs/api`).
+
+```sh
+php artisan vendor:publish --provider="Dedoc\Scramble\ScrambleServiceProvider" --tag="scramble-config"
+```
+
+The content of `scramble` config:
+
+```php
+<?php
+
+use Dedoc\Scramble\Http\Middleware\RestrictedDocsAccess;
+
+return [
+    /*
+     * Your API server base URL: will be used as base URL in docs.
+     */
+    'api_base_url' => url('/api'),
+
+    'info' => [
+        /*
+         * API version.
+         */
+        'version' => env('API_VERSION', '0.0.1'),
+
+        /*
+         * Description rendered on the home page of the API documentation (`/docs/api`).
+         */
+        'description' => '',
+    ],
+
+    'middleware' => [
+        'web',
+        RestrictedDocsAccess::class,
+    ],
+
+    'extensions' => [],
+];
+```

docs/usage/response.md

@@ -8,7 +8,9 @@ Based on source code analysis, Scramble can generate endpoint responses document
 - `JsonResource` response
 - `AnonymousResourceCollection` of `JsonResource` items
 - Some `response()` (`ResponseFactory`) support: `response()->make(...)`, `response()->json(...)`, `response()->noContent()`
+- Manually constructed `JsonResponse` and `Response` (using `new`)
 - `LengthAwarePaginator` of `JsonResource` items
+- Models
 
 First three can be understood automatically from the code. The latest one needs to be documented in PhpDoc for now.
 
@@ -84,7 +86,6 @@ All resource property types that are accessed on `$this` or `$this->resource` ar
 
 <aside>
 💡 You need to have `doctrine/dbal` package installed for this to work.
-
 </aside>
 
 By default, Scramble tries to find a model in `App\\Models\\` namespace, based on resource name. Before the lookup resource name is converted to singular form (`TodoItemsResource` → `TodoItem`).
@@ -223,6 +224,23 @@ class TodoItemsController
 }
 ```
 
+## Models
+
+When you don't have a resource and simply return a model from controller's method, Scramble will be able to document that as well.
+
+When documenting models, Scramble will document what model's `toArray` return. So if `toArray` is overridden, it should return array to be properly analyzed.
+
+```php
+public function show(Request $request, User $user)
+{
+    return $user;
+}
+```
+
+<aside>
+Please note that if you don't type annotate method's return type, model type should be specified in arguments list. Otherwise, Scramble won't be able to infer returned variable type and document it properly. Also, now only relations that always present on a model (`$with` property) are documented.
+</aside> 
+
 ## LengthAwarePaginator response
 
 Paginated response cannot be inferred from code automatically so you need to typehint it manually in PhpDoc like so:
@@ -248,7 +266,7 @@ class TodoItemsController
 
 This will add all the meta and other information to the docs.
 
-## Arbitrary response types
+## Arbitrary responses
 
 If nothing from above works, and something custom needed, you can use PhpStan PhpDoc format and document return type of the method:
 
@@ -271,3 +289,29 @@ class TodoItemsController
     }
 }
 ```
+
+## Response description
+
+Description can be added to the response by adding a comment right before the `return` in a controller.
+```php
+public function show(Request $request, User $user)
+{
+    // A user resource.
+    return new UserResource($user);
+}
+```
+
+Response status and type can be added manually as well using `@status` and `@body` tags in PhpDoc block before the `return`.
+```php
+public function create(Request $request)
+{
+    /**
+     * A user resource.
+     * 
+     * @status 201
+     * @body User
+     */
+    return User::create($request->only(['email']));
+}
+```
+

docs/usage/security.md

@@ -32,7 +32,7 @@ public function boot()
 }
 ```
 
-## Examples
+## Security scheme examples
 Here are some common examples of the security schemes object you may have in your API. For full list of available methods check implementation of `SecurityScheme` class.
 
 ### API Key
@@ -59,3 +59,17 @@ SecurityScheme::oauth2()
             ->addScope('write:pets', 'modify pets in your account');
     });
 ```
+
+## Excluding a route from security requirements
+
+You can exclude a route from security requirements by adding `@unauthenticated` annotation to the route method's PhpDoc comment block.
+
+```php
+/**
+ * @unauthenticated
+ */
+public function index(Request $request)
+{
+    return response()->json(/* some data */);
+}
+```

src/Generator.php

@@ -36,7 +36,7 @@ public function __invoke()
             ->filter() // Closure based routes are filtered out for now, right here
             ->each(fn (Operation $operation) => $openApi->addPath(
                 Path::make(
-                    str_replace(config('scramble.base_url', url('/api')).'/', '', url($operation->path))
+                    str_replace(config('scramble.api_base_url', url('/api')).'/', '', url($operation->path))
                 )->addOperation($operation)
             ))
             ->toArray();
@@ -58,7 +58,7 @@ private function makeOpenApi()
                     ->setDescription(config('scramble.info.description', ''))
             );
 
-        $openApi->addServer(Server::make(config('scramble.base_url', url('/api'))));
+        $openApi->addServer(Server::make(config('scramble.api_base_url', url('/api'))));
 
         return $openApi;
     }