Installation & setup

1
composer require dedoc/scramble

1
php artisan vendor:publish --provider="Dedoc\Scramble\ScrambleServiceProvider" --tag="scramble-config"

1
<?php
2

3
use Dedoc\Scramble\Http\Middleware\RestrictedDocsAccess;
4

5
return [
6
    /*
7
     * Which routes to document. String or array form; use Scramble::routes() for custom selection.
8
     *
9
     * 'api_path' => [
10
     *     'include' => 'api',
11
     *     'exclude' => ['api/internal'],
12
     * ],
13
     *
14
     * Without *, patterns match path segments (api matches api and api/users, not apiary).
15
     * With *, Str::is is used (e.g. api/v*).
16
     *
17
     * One static include → default server is /{include} and paths are stripped (/users).
18
     * Multiple includes or wildcards → server defaults to / and paths stay full (/api/users).
19
     * Override with `servers`, or use Scramble::registerApi() for separate bases.
20
     */
21
    'api_path' => 'api',
22

23
    /*
24
     * Your API domain. By default, app domain is used. This is also a part of the default API routes
25
     * matcher, so when implementing your own, make sure you use this config if needed.
26
     */
27
    'api_domain' => null,
28

29
    /*
30
     * The path where your OpenAPI specification will be exported.
31
     */
32
    'export_path' => 'api.json',
33

34
    /*
35
     * Cache configuration for the generated OpenAPI document.
36
     *
37
     * Use `scramble:cache` to warm the cache and `scramble:clear` to invalidate it.
38
     */
39
    'cache' => [
40
        'key' => 'scramble.openapi',
41
        'store' => 'file',
42
    ],
43

44
    'info' => [
45
        /*
46
         * API version.
47
         */
48
        'version' => env('API_VERSION', '0.0.1'),
49

50
        /*
51
         * Description rendered on the home page of the API documentation (`/docs/api`).
52
         */
53
        'description' => '',
54
    ],
55

56
    'ui' => [
57
        'title' => null,
58
    ],
59

60
    'renderer' => 'elements',
61

62
    'renderers' => [
63
        /*
64
         * Stoplight Elements config options: https://docs.stoplight.io/docs/elements/b074dc47b2826-elements-configuration-options
65
         */
66
        'elements' => [
67
            'view' => 'scramble::docs',
68
            'theme' => 'light',
69
            'hideTryIt' => false,
70
            'hideSchemas' => false,
71
            'logo' => '',
72
            'tryItCredentialsPolicy' => 'include',
73
            'layout' => 'responsive',
74
            'router' => 'hash',
75
        ],
76
        /*
77
         * Scalar API reference config options: https://scalar.com/products/api-references/configuration
78
         */
79
        'scalar' => [
80
            'view' => 'scramble::scalar',
81
            'cdn' => 'https://cdn.jsdelivr.net/npm/@scalar/api-reference',
82
            'theme' => 'laravel',
83
            'proxyUrl' => 'https://proxy.scalar.com',
84
            'darkMode' => false,
85
            'showDeveloperTools' => 'never',
86
            'agent' => ['disabled' => true],
87
            'credentials' => 'include',
88
        ],
89
    ],
90

91
    /*
92
     * The list of servers of the API. By default, when `null`, server URL will be created from
93
     * `scramble.api_path` and `scramble.api_domain` config variables. When providing an array, you
94
     * will need to specify the local server URL manually (if needed).
95
     *
96
     * Example of non-default config (final URLs are generated using Laravel `url` helper):
97
     *
98
     * ```php
99
     * 'servers' => [
100
     *     'Live' => 'api',
101
     *     'Prod' => 'https://scramble.dedoc.co/api',
102
     * ],
103
     * ```
104
     */
105
    'servers' => null,
106

107
    /**
108
     * Determines how Scramble stores the descriptions of enum cases.
109
     * Available options:
110
     * - 'description' – Case descriptions are stored as the enum schema's description using table formatting.
111
     * - 'extension' – Case descriptions are stored in the `x-enumDescriptions` enum schema extension.
112
     *
113
     *    @see https://redocly.com/docs-legacy/api-reference-docs/specification-extensions/x-enum-descriptions
114
     * - false - Case descriptions are ignored.
115
     */
116
    'enum_cases_description_strategy' => 'description',
117

118
    /**
119
     * Determines how Scramble stores the names of enum cases.
120
     * Available options:
121
     * - 'names' – Case names are stored in the `x-enumNames` enum schema extension.
122
     * - 'varnames' - Case names are stored in the `x-enum-varnames` enum schema extension.
123
     * - false - Case names are not stored.
124
     */
125
    'enum_cases_names_strategy' => false,
126

127
    /**
128
     * When Scramble encounters deep objects in query parameters, it flattens the parameters so the generated
129
     * OpenAPI document correctly describes the API. Flattening deep query parameters is relevant until
130
     * OpenAPI 3.2 is released and query string structure can be described properly.
131
     *
132
     * For example, this nested validation rule describes the object with `bar` property:
133
     * `['foo.bar' => ['required', 'int']]`.
134
     *
135
     * When `flatten_deep_query_parameters` is `true`, Scramble will document the parameter like so:
136
     * `{"name":"foo[bar]", "schema":{"type":"int"}, "required":true}`.
137
     *
138
     * When `flatten_deep_query_parameters` is `false`, Scramble will document the parameter like so:
139
     *  `{"name":"foo", "schema": {"type":"object", "properties":{"bar":{"type": "int"}}, "required": ["bar"]}, "required":true}`.
140
     */
141
    'flatten_deep_query_parameters' => true,
142

143
    'middleware' => [
144
        'web',
145
        RestrictedDocsAccess::class,
146
    ],
147

148
    'extensions' => [],
149

150
    /*
151
     * Automatically document API security (OpenAPI `security` / `securitySchemes`) based on route
152
     * middleware.
153
     *
154
     * Disabled by default. Uncomment the line below to enable `MiddlewareAuthSecurityStrategy`.
155
     * When at least one documented route uses middleware matching the configured patterns (by default
156
     * `auth` and `auth:*`), bearer auth is applied globally. Routes without matching middleware are
157
     * marked as public (`security: []`).
158
     *
159
     * Set to `null` explicitly to disable. If you already configure security manually via
160
     * `afterOpenApiGenerated` / `extendOpenApi`, keep this disabled to avoid duplicate schemes.
161
     *
162
     * Customize with a class-string or [class, options]:
163
     *
164
     * 'security_strategy' => [
165
     *     \Dedoc\Scramble\SecurityDocumentation\MiddlewareAuthSecurityStrategy::class,
166
     *     [
167
     *         'middleware' => ['auth', 'auth:*'],
168
     *         'scheme' => \Dedoc\Scramble\Support\Generator\SecurityScheme::http('bearer'),
169
     *     ],
170
     * ],
171
     */
172
    // 'security_strategy' => \Dedoc\Scramble\SecurityDocumentation\MiddlewareAuthSecurityStrategy::class,
173
    'security_strategy' => null,
174
];