Skip to content

Commit a271156

Browse files
shalvahshalvah
committed
Update docs
1 parent 17290be commit a271156

File tree

9 files changed

+701
-2298
lines changed

9 files changed

+701
-2298
lines changed

‎config/scribe.php‎

Lines changed: 88 additions & 117 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
<?php
22

3+
use Knuckles\Scribe\Extracting\Strategies;
34
use App\Docs\Strategies\AddPaginationParameters;
45

56
return [
@@ -28,109 +29,80 @@
2829
*/
2930
'routes' => [
3031
[
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' => [
3137
/*
32-
* Specify conditions to determine what routes will be a part of this group.
33-
* A route must fulfill ALL conditions to be included.
38+
* Match only routes whose domains match this pattern (use * as a wildcard to match any characters). Example: 'api.*'.
3439
*/
35-
'match' => [
36-
/*
37-
* Match only routes whose domains match this pattern (use * as a wildcard to match any characters). Example: 'api.*'.
38-
*/
39-
'domains' => ['*'],
40-
41-
/*
42-
* Match only routes whose paths match this pattern (use * as a wildcard to match any characters). Example: 'users/*'.
43-
*/
44-
'prefixes' => ['api/*'],
45-
46-
/*
47-
* [Dingo router only] Match only routes registered under this version. Wildcards are not supported.
48-
*/
49-
'versions' => ['v1'],
50-
],
51-
40+
'domains' => ['*'],
5241
/*
53-
* Include these routes even if they did not match the rules above.
54-
* The route can be referenced by name or path here. Wildcards are supported.
42+
* Match only routes whose paths match this pattern (use * as a wildcard to match any characters). Example: 'users/*'.
5543
*/
56-
'include' => [
57-
// 'users.index', 'healthcheck*'
58-
],
59-
44+
'prefixes' => ['api/*'],
6045
/*
61-
* Exclude these routes even if they matched the rules above.
62-
* The route can be referenced by name or path here. Wildcards are supported.
46+
* [Dingo router only] Match only routes registered under this version. Wildcards are not supported.
6347
*/
64-
'exclude' => [
65-
// '/health', 'admin.*'
66-
],
67-
48+
'versions' => ['v1'],
49+
],
50+
/*
51+
* Include these routes even if they did not match the rules above.
52+
* The route can be referenced by name or path here. Wildcards are supported.
53+
*/
54+
'include' => [],
55+
/*
56+
* Exclude these routes even if they matched the rules above.
57+
* The route can be referenced by name or path here. Wildcards are supported.
58+
*/
59+
'exclude' => [],
60+
/*
61+
* Settings to be applied to all the matched routes in this group when generating documentation
62+
*/
63+
'apply' => [
6864
/*
69-
* Settings to be applied to all the matched routes in this group when generating documentation
65+
* Additional headers to be added to the example requests
7066
*/
71-
'apply' => [
67+
'headers' => ['Content-Type' => 'application/json', 'Accept' => 'application/json'],
68+
/*
69+
* If no @response or @transformer declarations are found for the route,
70+
* Scribe will try to get a sample response by attempting an API call.
71+
* Configure the settings for the API call here.
72+
*/
73+
'response_calls' => [
7274
/*
73-
* Additional headers to be added to the example requests
75+
* API calls will be made only for routes in this group matching these HTTP methods (GET, POST, etc).
76+
* List the methods here or use '*' to mean all methods. Leave empty to disable API calls.
7477
*/
75-
'headers' => [
76-
'Content-Type' => 'application/json',
77-
'Accept' => 'application/json',
78-
],
79-
78+
'methods' => ['GET'],
79+
/*
80+
* Laravel config variables which should be set for the API call.
81+
* This is a good place to ensure that notifications, emails and other external services
82+
* are not triggered during the documentation API calls.
83+
* You can also create a `.env.docs` file and run the generate command with `--env docs`.
84+
*/
85+
'config' => ['app.env' => 'documentation'],
86+
/*
87+
* Query parameters which should be sent with the API call.
88+
*/
89+
'queryParams' => [],
90+
/*
91+
* Body parameters which should be sent with the API call.
92+
*/
93+
'bodyParams' => [],
8094
/*
81-
* If no @response or @transformer declarations are found for the route,
82-
* Scribe will try to get a sample response by attempting an API call.
83-
* Configure the settings for the API call here.
95+
* Files which should be sent with the API call.
96+
* 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).
8497
*/
85-
'response_calls' => [
86-
/*
87-
* API calls will be made only for routes in this group matching these HTTP methods (GET, POST, etc).
88-
* List the methods here or use '*' to mean all methods. Leave empty to disable API calls.
89-
*/
90-
'methods' => ['GET'],
91-
92-
/*
93-
* Laravel config variables which should be set for the API call.
94-
* This is a good place to ensure that notifications, emails and other external services
95-
* are not triggered during the documentation API calls.
96-
* You can also create a `.env.docs` file and run the generate command with `--env docs`.
97-
*/
98-
'config' => [
99-
'app.env' => 'documentation',
100-
// 'app.debug' => false,
101-
],
102-
103-
/*
104-
* Query parameters which should be sent with the API call.
105-
*/
106-
'queryParams' => [
107-
// 'key' => 'value',
108-
],
109-
110-
/*
111-
* Body parameters which should be sent with the API call.
112-
*/
113-
'bodyParams' => [
114-
// 'key' => 'value',
115-
],
116-
117-
/*
118-
* Files which should be sent with the API call.
119-
* 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).
120-
*/
121-
'fileParams' => [
122-
// 'key' => 'storage/app/image.png',
123-
],
124-
125-
/*
126-
* Cookies which should be sent with the API call.
127-
*/
128-
'cookies' => [
129-
// 'name' => 'value'
130-
],
131-
],
98+
'fileParams' => [],
99+
/*
100+
* Cookies which should be sent with the API call.
101+
*/
102+
'cookies' => [],
132103
],
133104
],
105+
]
134106
],
135107

136108
/*
@@ -252,7 +224,7 @@
252224
/*
253225
* Example requests for each endpoint will be shown in each of these languages.
254226
* Supported options are: bash, javascript, php, python
255-
* To add a language of your own, see https://scribe.readthedocs.io/en/latest/customization.html
227+
* To add a language of your own, see https://scribe.knuckles.wtf/laravel/advanced/adding-example-languages
256228
*
257229
*/
258230
'example_languages' => [
@@ -298,14 +270,13 @@
298270
],
299271

300272
/*
301-
* Name for the group of endpoints which do not have a @group set.
273+
* Endpoints which don't have a @group will be placed in this default group.
302274
*/
303275
'default_group' => 'General',
304276

305277
/*
306278
* Custom logo path. This will be used as the value of the src attribute for the <img> tag,
307-
* 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.
308-
* Set this to false to not use a logo.
279+
* so make sure it points to an accessible URL or path. Set to false to not use a logo.
309280
*
310281
* For example, if your logo is in public/img:
311282
* - 'logo' => '../img/logo.png' // for `static` type (output folder is public/docs)
@@ -322,45 +293,44 @@
322293

323294
/**
324295
* The strategies Scribe will use to extract information about your routes at each stage.
325-
* If you write or install a custom strategy, add it here.
296+
* If you create or install a custom strategy, add it here.
326297
*/
327298
'strategies' => [
328299
'metadata' => [
329-
\Knuckles\Scribe\Extracting\Strategies\Metadata\GetFromDocBlocks::class,
300+
Strategies\Metadata\GetFromDocBlocks::class,
330301
],
331302
'urlParameters' => [
332-
\Knuckles\Scribe\Extracting\Strategies\UrlParameters\GetFromLaravelAPI::class,
333-
\Knuckles\Scribe\Extracting\Strategies\UrlParameters\GetFromLumenAPI::class,
334-
\Knuckles\Scribe\Extracting\Strategies\UrlParameters\GetFromUrlParamTag::class,
303+
Strategies\UrlParameters\GetFromLaravelAPI::class,
304+
Strategies\UrlParameters\GetFromLumenAPI::class,
305+
Strategies\UrlParameters\GetFromUrlParamTag::class,
335306
],
336307
'queryParameters' => [
308+
Strategies\QueryParameters\GetFromFormRequest::class,
309+
Strategies\QueryParameters\GetFromInlineValidator::class,
310+
Strategies\QueryParameters\GetFromQueryParamTag::class,
337311
AddPaginationParameters::class,
338-
\Knuckles\Scribe\Extracting\Strategies\QueryParameters\GetFromQueryParamTag::class,
339312
],
340313
'headers' => [
341-
\Knuckles\Scribe\Extracting\Strategies\Headers\GetFromRouteRules::class,
342-
\Knuckles\Scribe\Extracting\Strategies\Headers\GetFromHeaderTag::class,
314+
Strategies\Headers\GetFromRouteRules::class,
315+
Strategies\Headers\GetFromHeaderTag::class,
343316
],
344317
'bodyParameters' => [
345-
\Knuckles\Scribe\Extracting\Strategies\BodyParameters\GetFromFormRequest::class,
346-
\Knuckles\Scribe\Extracting\Strategies\BodyParameters\GetFromInlineValidator::class,
347-
\Knuckles\Scribe\Extracting\Strategies\BodyParameters\GetFromBodyParamTag::class,
318+
Strategies\BodyParameters\GetFromFormRequest::class,
319+
Strategies\BodyParameters\GetFromInlineValidator::class,
320+
Strategies\BodyParameters\GetFromBodyParamTag::class,
348321
],
349322
'responses' => [
350-
\Knuckles\Scribe\Extracting\Strategies\Responses\UseTransformerTags::class,
351-
\Knuckles\Scribe\Extracting\Strategies\Responses\UseResponseTag::class,
352-
\Knuckles\Scribe\Extracting\Strategies\Responses\UseResponseFileTag::class,
353-
\Knuckles\Scribe\Extracting\Strategies\Responses\UseApiResourceTags::class,
354-
\Knuckles\Scribe\Extracting\Strategies\Responses\ResponseCalls::class,
323+
Strategies\Responses\UseTransformerTags::class,
324+
Strategies\Responses\UseResponseTag::class,
325+
Strategies\Responses\UseResponseFileTag::class,
326+
Strategies\Responses\UseApiResourceTags::class,
327+
Strategies\Responses\ResponseCalls::class,
355328
],
356329
'responseFields' => [
357-
\Knuckles\Scribe\Extracting\Strategies\ResponseFields\GetFromResponseFieldTag::class,
330+
Strategies\ResponseFields\GetFromResponseFieldTag::class,
358331
],
359332
],
360333

361-
/*
362-
* Configure how responses are transformed using @transformer and @transformerCollection (requires league/fractal package)
363-
*/
364334
'fractal' => [
365335
/* If you are using a custom serializer with league/fractal, you can specify it here.
366336
* Leave as null to use no serializer or return simple JSON.
@@ -369,15 +339,16 @@
369339
],
370340

371341
/*
372-
* [Advanced] If you would like to customize how routes are matched beyond the route configuration you may
373-
* declare your own implementation of RouteMatcherInterface
342+
* [Advanced] Custom implementation of RouteMatcherInterface to customise how routes are matched
374343
*
375344
*/
376345
'routeMatcher' => \Knuckles\Scribe\Matching\RouteMatcher::class,
377346

378347
/**
379-
* For response calls, api resource responses and transformer responses, Scribe will try to start database transactions, so no changes are persisted to your database.
380-
* Tell Scribe which connections should be transacted here. If you only use the default db connection, you can leave this as is.
348+
* For response calls, API resource responses and transformer responses,
349+
* Scribe will try to start database transactions, so no changes are persisted to your database.
350+
* Tell Scribe which connections should be transacted here.
351+
* If you only use one db connection, you can leave this as is.
381352
*/
382353
'database_connections_to_transact' => [config('database.default')]
383354
];

‎docs/CNAME‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

0 commit comments

Comments
 (0)