wip
This commit is contained in:
443
config/scribe.php
Normal file
443
config/scribe.php
Normal file
@@ -0,0 +1,443 @@
|
||||
<?php
|
||||
|
||||
use Knuckles\Scribe\Extracting\Strategies;
|
||||
|
||||
return [
|
||||
|
||||
'theme' => 'default',
|
||||
|
||||
/*
|
||||
* The HTML <title> for the generated documentation. If this is empty, Scribe will infer it from config('app.name').
|
||||
*/
|
||||
'title' => null,
|
||||
|
||||
/*
|
||||
* A short description of your API. Will be included in the docs webpage, Postman collection and OpenAPI spec.
|
||||
*/
|
||||
'description' => '',
|
||||
|
||||
/*
|
||||
* The base URL displayed in the docs. If this is empty, Scribe will use the value of config('app.url').
|
||||
*/
|
||||
'base_url' => null,
|
||||
|
||||
/*
|
||||
* Tell Scribe what routes to generate documentation for.
|
||||
* Each group contains rules defining which routes should be included ('match', 'include' and 'exclude' sections)
|
||||
* and settings which should be applied to them ('apply' section).
|
||||
*/
|
||||
'routes' => [
|
||||
[
|
||||
/*
|
||||
* Specify conditions to determine what routes will be a part of this group.
|
||||
* A route must fulfill ALL conditions to be included.
|
||||
*/
|
||||
'match' => [
|
||||
/*
|
||||
* Match only routes whose paths match this pattern (use * as a wildcard to match any characters). Example: 'users/*'.
|
||||
*/
|
||||
'prefixes' => ['api/*'],
|
||||
|
||||
/*
|
||||
* Match only routes whose domains match this pattern (use * as a wildcard to match any characters). Example: 'api.*'.
|
||||
*/
|
||||
'domains' => ['*'],
|
||||
|
||||
/*
|
||||
* [Dingo router only] Match only routes registered under this version. Wildcards are not supported.
|
||||
*/
|
||||
'versions' => [],
|
||||
],
|
||||
|
||||
/*
|
||||
* Include these routes even if they did not match the rules above.
|
||||
* The route can be referenced by name or path here. Wildcards are supported.
|
||||
*/
|
||||
'include' => [
|
||||
// 'users.index', 'healthcheck*'
|
||||
],
|
||||
|
||||
/*
|
||||
* Exclude these routes even if they matched the rules above.
|
||||
* The route can be referenced by name or path here. Wildcards are supported.
|
||||
*/
|
||||
'exclude' => [
|
||||
// '/health', 'admin.*'
|
||||
],
|
||||
|
||||
/*
|
||||
* Settings to be applied to all the matched routes in this group when generating documentation
|
||||
*/
|
||||
'apply' => [
|
||||
/*
|
||||
* Additional headers to be added to the example requests
|
||||
*/
|
||||
'headers' => [
|
||||
'Content-Type' => 'application/json',
|
||||
'Accept' => 'application/json',
|
||||
],
|
||||
|
||||
/*
|
||||
* If no @response or @transformer declarations are found for the route,
|
||||
* Scribe will try to get a sample response by attempting an API call.
|
||||
* Configure the settings for the API call here.
|
||||
*/
|
||||
'response_calls' => [
|
||||
/*
|
||||
* API calls will be made only for routes in this group matching these HTTP methods (GET, POST, etc).
|
||||
* List the methods here or use '*' to mean all methods. Leave empty to disable API calls.
|
||||
*/
|
||||
'methods' => ['GET', 'POST'],
|
||||
|
||||
/*
|
||||
* Laravel config variables which should be set for the API call.
|
||||
* This is a good place to ensure that notifications, emails and other external services
|
||||
* are not triggered during the documentation API calls.
|
||||
* You can also create a `.env.docs` file and run the generate command with `--env docs`.
|
||||
*/
|
||||
'config' => [
|
||||
'app.env' => 'documentation',
|
||||
// 'app.debug' => false,
|
||||
],
|
||||
|
||||
/*
|
||||
* Query parameters which should be sent with the API call.
|
||||
*/
|
||||
'queryParams' => [
|
||||
// 'key' => 'value',
|
||||
],
|
||||
|
||||
/*
|
||||
* Body parameters which should be sent with the API call.
|
||||
*/
|
||||
'bodyParams' => [
|
||||
// 'key' => 'value',
|
||||
],
|
||||
|
||||
/*
|
||||
* Files which should be sent with the API call.
|
||||
* 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).
|
||||
*/
|
||||
'fileParams' => [
|
||||
// 'key' => 'storage/app/image.png',
|
||||
],
|
||||
|
||||
/*
|
||||
* Cookies which should be sent with the API call.
|
||||
*/
|
||||
'cookies' => [
|
||||
// 'name' => 'value'
|
||||
],
|
||||
],
|
||||
],
|
||||
],
|
||||
],
|
||||
|
||||
/*
|
||||
* The type of documentation output to generate.
|
||||
* - "static" will generate a static HTMl page in the /public/docs folder,
|
||||
* - "laravel" will generate the documentation as a Blade view, so you can add routing and authentication.
|
||||
*/
|
||||
'type' => 'static',
|
||||
|
||||
/*
|
||||
* Settings for `static` type output.
|
||||
*/
|
||||
'static' => [
|
||||
/*
|
||||
* HTML documentation, assets and Postman collection will be generated to this folder.
|
||||
* Source Markdown will still be in resources/docs.
|
||||
*/
|
||||
'output_path' => 'public/docs',
|
||||
],
|
||||
|
||||
/*
|
||||
* Settings for `laravel` type output.
|
||||
*/
|
||||
'laravel' => [
|
||||
/*
|
||||
* Whether to automatically create a docs endpoint for you to view your generated docs.
|
||||
* If this is false, you can still set up routing manually.
|
||||
*/
|
||||
'add_routes' => true,
|
||||
|
||||
/*
|
||||
* URL path to use for the docs endpoint (if `add_routes` is true).
|
||||
* By default, `/docs` opens the HTML page, `/docs.postman` opens the Postman collection, and `/docs.openapi` the OpenAPI spec.
|
||||
*/
|
||||
'docs_url' => '/docs',
|
||||
|
||||
/*
|
||||
* Directory within `public` in which to store CSS and JS assets.
|
||||
* By default, assets are stored in `public/vendor/scribe`.
|
||||
* If set, assets will be stored in `public/{{assets_directory}}`
|
||||
*/
|
||||
'assets_directory' => null,
|
||||
|
||||
/*
|
||||
* Middleware to attach to the docs endpoint (if `add_routes` is true).
|
||||
*/
|
||||
'middleware' => [],
|
||||
],
|
||||
|
||||
'try_it_out' => [
|
||||
/**
|
||||
* Add a Try It Out button to your endpoints so consumers can test endpoints right from their browser.
|
||||
* Don't forget to enable CORS headers for your endpoints.
|
||||
*/
|
||||
'enabled' => true,
|
||||
|
||||
/**
|
||||
* The base URL for the API tester to use (for example, you can set this to your staging URL).
|
||||
* Leave as null to use the current app URL (config(app.url)).
|
||||
*/
|
||||
'base_url' => null,
|
||||
|
||||
/**
|
||||
* Fetch a CSRF token before each request, and add it as an X-XSRF-TOKEN header. Needed if you're using Laravel Sanctum.
|
||||
*/
|
||||
'use_csrf' => false,
|
||||
|
||||
/**
|
||||
* The URL to fetch the CSRF token from (if `use_csrf` is true).
|
||||
*/
|
||||
'csrf_url' => '/sanctum/csrf-cookie',
|
||||
],
|
||||
|
||||
/*
|
||||
* How is your API authenticated? This information will be used in the displayed docs, generated examples and response calls.
|
||||
*/
|
||||
'auth' => [
|
||||
/*
|
||||
* Set this to true if any endpoints in your API use authentication.
|
||||
*/
|
||||
'enabled' => true,
|
||||
|
||||
/*
|
||||
* Set this to true if your API should be authenticated by default. If so, you must also set `enabled` (above) to true.
|
||||
* You can then use @unauthenticated or @authenticated on individual endpoints to change their status from the default.
|
||||
*/
|
||||
'default' => false,
|
||||
|
||||
/*
|
||||
* Where is the auth value meant to be sent in a request?
|
||||
* Options: query, body, basic, bearer, header (for custom header)
|
||||
*/
|
||||
'in' => 'bearer',
|
||||
|
||||
/*
|
||||
* The name of the auth parameter (eg token, key, apiKey) or header (eg Authorization, Api-Key).
|
||||
*/
|
||||
'name' => 'key',
|
||||
|
||||
/*
|
||||
* The value of the parameter to be used by Scribe to authenticate response calls.
|
||||
* This will NOT be included in the generated documentation.
|
||||
* If this value is empty, Scribe will use a random value.
|
||||
*/
|
||||
'use_value' => env('SCRIBE_AUTH_KEY'),
|
||||
|
||||
/*
|
||||
* Placeholder your users will see for the auth parameter in the example requests.
|
||||
* Set this to null if you want Scribe to use a random value as placeholder instead.
|
||||
*/
|
||||
'placeholder' => '{YOUR_AUTH_KEY}',
|
||||
|
||||
/*
|
||||
* Any extra authentication-related info for your users. For instance, you can describe how to find or generate their auth credentials.
|
||||
* Markdown and HTML are supported.
|
||||
*/
|
||||
'extra_info' => 'You can retrieve your token by visiting your dashboard and clicking <b>Generate API token</b>.',
|
||||
],
|
||||
|
||||
/*
|
||||
* Text to place in the "Introduction" section, right after the `description`. Markdown and HTML are supported.
|
||||
*/
|
||||
'intro_text' => <<<'INTRO'
|
||||
This documentation aims to provide all the information you need to work with our API.
|
||||
|
||||
<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).
|
||||
You can switch the language used with the tabs at the top right (or from the nav menu at the top left on mobile).</aside>
|
||||
INTRO
|
||||
,
|
||||
|
||||
/*
|
||||
* Example requests for each endpoint will be shown in each of these languages.
|
||||
* Supported options are: bash, javascript, php, python
|
||||
* To add a language of your own, see https://scribe.knuckles.wtf/laravel/advanced/example-requests
|
||||
*
|
||||
*/
|
||||
'example_languages' => [
|
||||
'bash',
|
||||
'javascript',
|
||||
],
|
||||
|
||||
/*
|
||||
* Generate a Postman collection (v2.1.0) in addition to HTML docs.
|
||||
* For 'static' docs, the collection will be generated to public/docs/collection.json.
|
||||
* For 'laravel' docs, it will be generated to storage/app/scribe/collection.json.
|
||||
* Setting `laravel.add_routes` to true (above) will also add a route for the collection.
|
||||
*/
|
||||
'postman' => [
|
||||
'enabled' => true,
|
||||
|
||||
/*
|
||||
* Manually override some generated content in the spec. Dot notation is supported.
|
||||
*/
|
||||
'overrides' => [
|
||||
// 'info.version' => '2.0.0',
|
||||
],
|
||||
],
|
||||
|
||||
/*
|
||||
* Generate an OpenAPI spec (v3.0.1) in addition to docs webpage.
|
||||
* For 'static' docs, the collection will be generated to public/docs/openapi.yaml.
|
||||
* For 'laravel' docs, it will be generated to storage/app/scribe/openapi.yaml.
|
||||
* Setting `laravel.add_routes` to true (above) will also add a route for the spec.
|
||||
*/
|
||||
'openapi' => [
|
||||
'enabled' => true,
|
||||
|
||||
/*
|
||||
* Manually override some generated content in the spec. Dot notation is supported.
|
||||
*/
|
||||
'overrides' => [
|
||||
// 'info.version' => '2.0.0',
|
||||
],
|
||||
],
|
||||
|
||||
'groups' => [
|
||||
/*
|
||||
* Endpoints which don't have a @group will be placed in this default group.
|
||||
*/
|
||||
'default' => 'Endpoints',
|
||||
|
||||
/*
|
||||
* By default, Scribe will sort groups alphabetically, and endpoints in the order their routes are defined.
|
||||
* You can override this by listing the groups, subgroups and endpoints here in the order you want them.
|
||||
*
|
||||
* Any groups, subgroups or endpoints you don't list here will be added as usual after the ones here.
|
||||
* If an endpoint/subgroup is listed under a group it doesn't belong in, it will be ignored.
|
||||
* Note: you must include the initial '/' when writing an endpoint.
|
||||
*/
|
||||
'order' => [
|
||||
// 'This group will come first',
|
||||
// 'This group will come next' => [
|
||||
// 'POST /this-endpoint-will-comes-first',
|
||||
// 'GET /this-endpoint-will-comes-next',
|
||||
// ],
|
||||
// 'This group will come third' => [
|
||||
// 'This subgroup will come first' => [
|
||||
// 'GET /this-other-endpoint-will-comes-first',
|
||||
// 'GET /this-other-endpoint-will-comes-next',
|
||||
// ]
|
||||
// ]
|
||||
],
|
||||
],
|
||||
|
||||
/*
|
||||
* Custom logo path. This will be used as the value of the src attribute for the <img> tag,
|
||||
* so make sure it points to an accessible URL or path. Set to false to not use a logo.
|
||||
*
|
||||
* For example, if your logo is in public/img:
|
||||
* - 'logo' => '../img/logo.png' // for `static` type (output folder is public/docs)
|
||||
* - 'logo' => 'img/logo.png' // for `laravel` type
|
||||
*
|
||||
*/
|
||||
'logo' => false,
|
||||
|
||||
/**
|
||||
* Customize the "Last updated" value displayed in the docs by specifying tokens and formats.
|
||||
* Examples:
|
||||
* - {date:F j Y} => March 28, 2022
|
||||
* - {git:short} => Short hash of the last Git commit
|
||||
*
|
||||
* Available tokens are `{date:<format>}` and `{git:<format>}`.
|
||||
* The format you pass to `date` will be passed to PHP's `date()` function.
|
||||
* The format you pass to `git` can be either "short" or "long".
|
||||
*/
|
||||
'last_updated' => 'Last updated: {date:F j, Y}',
|
||||
|
||||
'examples' => [
|
||||
/*
|
||||
* If you would like the package to generate the same example values for parameters on each run,
|
||||
* set this to any number (eg. 1234)
|
||||
*/
|
||||
'faker_seed' => null,
|
||||
|
||||
/*
|
||||
* With API resources and transformers, Scribe tries to generate example models to use in your API responses.
|
||||
* By default, Scribe will try the model's factory, and if that fails, try fetching the first from the database.
|
||||
* You can reorder or remove strategies here.
|
||||
*/
|
||||
'models_source' => ['factoryCreate', 'factoryMake', 'databaseFirst'],
|
||||
],
|
||||
|
||||
/**
|
||||
* The strategies Scribe will use to extract information about your routes at each stage.
|
||||
* If you create or install a custom strategy, add it here.
|
||||
*/
|
||||
'strategies' => [
|
||||
'metadata' => [
|
||||
Strategies\Metadata\GetFromDocBlocks::class,
|
||||
Strategies\Metadata\GetFromMetadataAttributes::class,
|
||||
],
|
||||
'urlParameters' => [
|
||||
Strategies\UrlParameters\GetFromLaravelAPI::class,
|
||||
Strategies\UrlParameters\GetFromLumenAPI::class,
|
||||
Strategies\UrlParameters\GetFromUrlParamAttribute::class,
|
||||
Strategies\UrlParameters\GetFromUrlParamTag::class,
|
||||
],
|
||||
'queryParameters' => [
|
||||
Strategies\QueryParameters\GetFromFormRequest::class,
|
||||
Strategies\QueryParameters\GetFromInlineValidator::class,
|
||||
Strategies\QueryParameters\GetFromQueryParamAttribute::class,
|
||||
Strategies\QueryParameters\GetFromQueryParamTag::class,
|
||||
],
|
||||
'headers' => [
|
||||
Strategies\Headers\GetFromRouteRules::class,
|
||||
Strategies\Headers\GetFromHeaderAttribute::class,
|
||||
Strategies\Headers\GetFromHeaderTag::class,
|
||||
],
|
||||
'bodyParameters' => [
|
||||
Strategies\BodyParameters\GetFromFormRequest::class,
|
||||
Strategies\BodyParameters\GetFromInlineValidator::class,
|
||||
Strategies\BodyParameters\GetFromBodyParamAttribute::class,
|
||||
Strategies\BodyParameters\GetFromBodyParamTag::class,
|
||||
],
|
||||
'responses' => [
|
||||
Strategies\Responses\UseResponseAttributes::class,
|
||||
Strategies\Responses\UseTransformerTags::class,
|
||||
Strategies\Responses\UseApiResourceTags::class,
|
||||
Strategies\Responses\UseResponseTag::class,
|
||||
Strategies\Responses\UseResponseFileTag::class,
|
||||
Strategies\Responses\ResponseCalls::class,
|
||||
],
|
||||
'responseFields' => [
|
||||
Strategies\ResponseFields\GetFromResponseFieldAttribute::class,
|
||||
Strategies\ResponseFields\GetFromResponseFieldTag::class,
|
||||
],
|
||||
],
|
||||
|
||||
'fractal' => [
|
||||
/* If you are using a custom serializer with league/fractal, you can specify it here.
|
||||
* Leave as null to use no serializer or return simple JSON.
|
||||
*/
|
||||
'serializer' => null,
|
||||
],
|
||||
|
||||
/*
|
||||
* [Advanced] Custom implementation of RouteMatcherInterface to customise how routes are matched
|
||||
*
|
||||
*/
|
||||
'routeMatcher' => \Knuckles\Scribe\Matching\RouteMatcher::class,
|
||||
|
||||
/**
|
||||
* For response calls, API resource responses and transformer responses,
|
||||
* Scribe will try to start database transactions, so no changes are persisted to your database.
|
||||
* Tell Scribe which connections should be transacted here.
|
||||
* If you only use one db connection, you can leave this as is.
|
||||
*/
|
||||
'database_connections_to_transact' => [config('database.default')],
|
||||
'external' => ['html_attributes' => []],
|
||||
];
|
||||
Reference in New Issue
Block a user