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