scribe.php (17109B)
1 <?php 2 3 use Knuckles\Scribe\Extracting\Strategies; 4 5 return [ 6 7 'theme' => 'default', 8 9 /* 10 * The HTML <title> for the generated documentation. If this is empty, Scribe will infer it from config('app.name'). 11 */ 12 'title' => null, 13 14 /* 15 * A short description of your API. Will be included in the docs webpage, Postman collection and OpenAPI spec. 16 */ 17 'description' => '', 18 19 /* 20 * The base URL displayed in the docs. If this is empty, Scribe will use the value of config('app.url') at generation time. 21 * If you're using `laravel` type, you can set this to a dynamic string, like '{{ config("app.tenant_url") }}' to get a dynamic base URL. 22 */ 23 'base_url' => null, 24 25 /* 26 * Tell Scribe what routes to generate documentation for. 27 * Each group contains rules defining which routes should be included ('match', 'include' and 'exclude' sections) 28 * and settings which should be applied to them ('apply' section). 29 */ 30 'routes' => [ 31 [ 32 /* 33 * Specify conditions to determine what routes will be a part of this group. 34 * A route must fulfill ALL conditions to be included. 35 */ 36 'match' => [ 37 /* 38 * Match only routes whose paths match this pattern (use * as a wildcard to match any characters). Example: 'users/*'. 39 */ 40 'prefixes' => ['api/*'], 41 42 /* 43 * Match only routes whose domains match this pattern (use * as a wildcard to match any characters). Example: 'api.*'. 44 */ 45 'domains' => ['*'], 46 47 /* 48 * [Dingo router only] Match only routes registered under this version. Wildcards are not supported. 49 */ 50 'versions' => ['v1'], 51 ], 52 53 /* 54 * Include these routes even if they did not match the rules above. 55 * The route can be referenced by name or path here. Wildcards are supported. 56 */ 57 'include' => [ 58 // 'users.index', 'healthcheck*' 59 ], 60 61 /* 62 * Exclude these routes even if they matched the rules above. 63 * The route can be referenced by name or path here. Wildcards are supported. 64 */ 65 'exclude' => [ 66 // '/health', 'admin.*' 67 ], 68 69 /* 70 * Settings to be applied to all the matched routes in this group when generating documentation 71 */ 72 'apply' => [ 73 /* 74 * Additional headers to be added to the example requests 75 */ 76 'headers' => [ 77 'Content-Type' => 'application/json', 78 'Accept' => 'application/json', 79 ], 80 81 /* 82 * If no @response or @transformer declarations are found for the route, 83 * Scribe will try to get a sample response by attempting an API call. 84 * Configure the settings for the API call here. 85 */ 86 'response_calls' => [ 87 /* 88 * API calls will be made only for routes in this group matching these HTTP methods (GET, POST, etc). 89 * List the methods here or use '*' to mean all methods. Leave empty to disable API calls. 90 */ 91 'methods' => ['GET'], 92 93 /* 94 * Laravel config variables which should be set for the API call. 95 * This is a good place to ensure that notifications, emails and other external services 96 * are not triggered during the documentation API calls. 97 * You can also create a `.env.docs` file and run the generate command with `--env docs`. 98 */ 99 'config' => [ 100 'app.env' => 'documentation', 101 // 'app.debug' => false, 102 ], 103 104 /* 105 * Query parameters which should be sent with the API call. 106 */ 107 'queryParams' => [ 108 // 'key' => 'value', 109 ], 110 111 /* 112 * Body parameters which should be sent with the API call. 113 */ 114 'bodyParams' => [ 115 // 'key' => 'value', 116 ], 117 118 /* 119 * Files which should be sent with the API call. 120 * Each value should be a valid path (absolute or relative to your project directory) to a file on this machine (but not in the project root). 121 */ 122 'fileParams' => [ 123 // 'key' => 'storage/app/image.png', 124 ], 125 126 /* 127 * Cookies which should be sent with the API call. 128 */ 129 'cookies' => [ 130 // 'name' => 'value' 131 ], 132 ], 133 ], 134 ], 135 ], 136 137 /* 138 * The type of documentation output to generate. 139 * - "static" will generate a static HTMl page in the /public/docs folder, 140 * - "laravel" will generate the documentation as a Blade view, so you can add routing and authentication. 141 */ 142 'type' => 'laravel', 143 144 /* 145 * Settings for `static` type output. 146 */ 147 'static' => [ 148 /* 149 * HTML documentation, assets and Postman collection will be generated to this folder. 150 * Source Markdown will still be in resources/docs. 151 */ 152 'output_path' => 'public/docs', 153 ], 154 155 /* 156 * Settings for `laravel` type output. 157 */ 158 'laravel' => [ 159 /* 160 * Whether to automatically create a docs endpoint for you to view your generated docs. 161 * If this is false, you can still set up routing manually. 162 */ 163 'add_routes' => true, 164 165 /* 166 * URL path to use for the docs endpoint (if `add_routes` is true). 167 * By default, `/docs` opens the HTML page, `/docs.postman` opens the Postman collection, and `/docs.openapi` the OpenAPI spec. 168 */ 169 'docs_url' => '/docs', 170 171 /* 172 * Directory within `public` in which to store CSS and JS assets. 173 * By default, assets are stored in `public/vendor/scribe`. 174 * If set, assets will be stored in `public/{{assets_directory}}` 175 */ 176 'assets_directory' => null, 177 178 /* 179 * Middleware to attach to the docs endpoint (if `add_routes` is true). 180 */ 181 'middleware' => [], 182 ], 183 184 'try_it_out' => [ 185 /** 186 * Add a Try It Out button to your endpoints so consumers can test endpoints right from their browser. 187 * Don't forget to enable CORS headers for your endpoints. 188 */ 189 'enabled' => true, 190 191 /** 192 * The base URL for the API tester to use (for example, you can set this to your staging URL). 193 * Leave as null to use the current app URL when generating (config("app.url")). 194 */ 195 'base_url' => null, 196 197 /** 198 * Fetch a CSRF token before each request, and add it as an X-XSRF-TOKEN header. Needed if you're using Laravel Sanctum. 199 */ 200 'use_csrf' => false, 201 202 /** 203 * The URL to fetch the CSRF token from (if `use_csrf` is true). 204 */ 205 'csrf_url' => '/sanctum/csrf-cookie', 206 ], 207 208 /* 209 * How is your API authenticated? This information will be used in the displayed docs, generated examples and response calls. 210 */ 211 'auth' => [ 212 /* 213 * Set this to true if any endpoints in your API use authentication. 214 */ 215 'enabled' => true, 216 217 /* 218 * Set this to true if your API should be authenticated by default. If so, you must also set `enabled` (above) to true. 219 * You can then use @unauthenticated or @authenticated on individual endpoints to change their status from the default. 220 */ 221 'default' => true, 222 223 /* 224 * Where is the auth value meant to be sent in a request? 225 * Options: query, body, basic, bearer, header (for custom header) 226 */ 227 'in' => 'bearer', 228 229 /* 230 * The name of the auth parameter (eg token, key, apiKey) or header (eg Authorization, Api-Key). 231 */ 232 'name' => 'Authorization', 233 234 /* 235 * The value of the parameter to be used by Scribe to authenticate response calls. 236 * This will NOT be included in the generated documentation. 237 * If this value is empty, Scribe will use a random value. 238 */ 239 'use_value' => env('SCRIBE_AUTH_KEY'), 240 241 /* 242 * Placeholder your users will see for the auth parameter in the example requests. 243 * Set this to null if you want Scribe to use a random value as placeholder instead. 244 */ 245 'placeholder' => '{YOUR_AUTH_KEY}', 246 247 /* 248 * Any extra authentication-related info for your users. For instance, you can describe how to find or generate their auth credentials. 249 * Markdown and HTML are supported. 250 */ 251 'extra_info' => 'You can retrieve your token by visiting your dashboard and clicking <b>Generate API token</b>.', 252 ], 253 254 /* 255 * Text to place in the "Introduction" section, right after the `description`. Markdown and HTML are supported. 256 */ 257 'intro_text' => <<<INTRO 258 This documentation aims to provide all the information you need to work with our API. 259 INTRO 260 , 261 262 /* 263 * Example requests for each endpoint will be shown in each of these languages. 264 * Supported options are: bash, javascript, php, python 265 * To add a language of your own, see https://scribe.knuckles.wtf/laravel/advanced/example-requests 266 * 267 */ 268 'example_languages' => [ 269 'bash', 270 'javascript', 271 ], 272 273 /* 274 * Generate a Postman collection (v2.1.0) in addition to HTML docs. 275 * For 'static' docs, the collection will be generated to public/docs/collection.json. 276 * For 'laravel' docs, it will be generated to storage/app/scribe/collection.json. 277 * Setting `laravel.add_routes` to true (above) will also add a route for the collection. 278 */ 279 'postman' => [ 280 'enabled' => true, 281 282 /* 283 * Manually override some generated content in the spec. Dot notation is supported. 284 */ 285 'overrides' => [ 286 // 'info.version' => '2.0.0', 287 ], 288 ], 289 290 /* 291 * Generate an OpenAPI spec (v3.0.1) in addition to docs webpage. 292 * For 'static' docs, the collection will be generated to public/docs/openapi.yaml. 293 * For 'laravel' docs, it will be generated to storage/app/scribe/openapi.yaml. 294 * Setting `laravel.add_routes` to true (above) will also add a route for the spec. 295 */ 296 'openapi' => [ 297 'enabled' => true, 298 299 /* 300 * Manually override some generated content in the spec. Dot notation is supported. 301 */ 302 'overrides' => [ 303 // 'info.version' => '2.0.0', 304 ], 305 ], 306 307 'groups' => [ 308 /* 309 * Endpoints which don't have a @group will be placed in this default group. 310 */ 311 'default' => 'Endpoints', 312 313 /* 314 * By default, Scribe will sort groups alphabetically, and endpoints in the order their routes are defined. 315 * You can override this by listing the groups, subgroups and endpoints here in the order you want them. 316 * 317 * Any groups, subgroups or endpoints you don't list here will be added as usual after the ones here unless you 318 * use the "*" character as this specifies the position of all unspecified groups 319 * If an endpoint/subgroup is listed under a group it doesn't belong in, it will be ignored. 320 * Note: you must include the initial '/' when writing an endpoint. 321 */ 322 'order' => [ 323 // 'This group will come first', 324 // 'This group will come next' => [ 325 // 'POST /this-endpoint-will-comes-first', 326 // 'GET /this-endpoint-will-comes-next', 327 // ], 328 // 'This group will come third' => [ 329 // 'This subgroup will come first' => [ 330 // 'GET /this-other-endpoint-will-comes-first', 331 // 'GET /this-other-endpoint-will-comes-next', 332 // ] 333 // ] 334 ], 335 ], 336 337 /* 338 * Custom logo path. This will be used as the value of the src attribute for the <img> tag, 339 * so make sure it points to an accessible URL or path. Set to false to not use a logo. 340 * 341 * For example, if your logo is in public/img: 342 * - 'logo' => '../img/logo.png' // for `static` type (output folder is public/docs) 343 * - 'logo' => 'img/logo.png' // for `laravel` type 344 * 345 */ 346 'logo' => false, 347 348 /** 349 * Customize the "Last updated" value displayed in the docs by specifying tokens and formats. 350 * Examples: 351 * - {date:F j Y} => March 28, 2022 352 * - {git:short} => Short hash of the last Git commit 353 * 354 * Available tokens are `{date:<format>}` and `{git:<format>}`. 355 * The format you pass to `date` will be passed to PHP's `date()` function. 356 * The format you pass to `git` can be either "short" or "long". 357 */ 358 'last_updated' => 'Last updated: {date:F j, Y}', 359 360 'examples' => [ 361 /* 362 * If you would like the package to generate the same example values for parameters on each run, 363 * set this to any number (eg. 1234) 364 */ 365 'faker_seed' => "12345", 366 367 /* 368 * With API resources and transformers, Scribe tries to generate example models to use in your API responses. 369 * By default, Scribe will try the model's factory, and if that fails, try fetching the first from the database. 370 * You can reorder or remove strategies here. 371 */ 372 'models_source' => ['factoryCreate', 'factoryMake', 'databaseFirst'], 373 ], 374 375 /** 376 * The strategies Scribe will use to extract information about your routes at each stage. 377 * If you create or install a custom strategy, add it here. 378 */ 379 'strategies' => [ 380 'metadata' => [ 381 Strategies\Metadata\GetFromDocBlocks::class, 382 Strategies\Metadata\GetFromMetadataAttributes::class, 383 ], 384 'urlParameters' => [ 385 Strategies\UrlParameters\GetFromLaravelAPI::class, 386 Strategies\UrlParameters\GetFromLumenAPI::class, 387 Strategies\UrlParameters\GetFromUrlParamAttribute::class, 388 Strategies\UrlParameters\GetFromUrlParamTag::class, 389 ], 390 'queryParameters' => [ 391 Strategies\QueryParameters\GetFromFormRequest::class, 392 Strategies\QueryParameters\GetFromInlineValidator::class, 393 Strategies\QueryParameters\GetFromQueryParamAttribute::class, 394 Strategies\QueryParameters\GetFromQueryParamTag::class, 395 ], 396 'headers' => [ 397 Strategies\Headers\GetFromRouteRules::class, 398 Strategies\Headers\GetFromHeaderAttribute::class, 399 Strategies\Headers\GetFromHeaderTag::class, 400 ], 401 'bodyParameters' => [ 402 Strategies\BodyParameters\GetFromFormRequest::class, 403 Strategies\BodyParameters\GetFromInlineValidator::class, 404 Strategies\BodyParameters\GetFromBodyParamAttribute::class, 405 Strategies\BodyParameters\GetFromBodyParamTag::class, 406 ], 407 'responses' => [ 408 Strategies\Responses\UseResponseAttributes::class, 409 Strategies\Responses\UseTransformerTags::class, 410 Strategies\Responses\UseApiResourceTags::class, 411 Strategies\Responses\UseResponseTag::class, 412 Strategies\Responses\UseResponseFileTag::class, 413 Strategies\Responses\ResponseCalls::class, 414 ], 415 'responseFields' => [ 416 Strategies\ResponseFields\GetFromResponseFieldAttribute::class, 417 Strategies\ResponseFields\GetFromResponseFieldTag::class, 418 ], 419 ], 420 421 'fractal' => [ 422 /* If you are using a custom serializer with league/fractal, you can specify it here. 423 * Leave as null to use no serializer or return simple JSON. 424 */ 425 'serializer' => null, 426 ], 427 428 /* 429 * [Advanced] Custom implementation of RouteMatcherInterface to customise how routes are matched 430 * 431 */ 432 'routeMatcher' => \Knuckles\Scribe\Matching\RouteMatcher::class, 433 434 /** 435 * For response calls, API resource responses and transformer responses, 436 * Scribe will try to start database transactions, so no changes are persisted to your database. 437 * Tell Scribe which connections should be transacted here. 438 * If you only use one db connection, you can leave this as is. 439 */ 440 'database_connections_to_transact' => [config('database.default')] 441 ];