mirror of
https://github.com/ambieco/scribe.git
synced 2026-04-29 18:46:25 +08:00
Update config comments
This commit is contained in:
shalvah
@@ -1,6 +1,130 @@
|
||||
<?php
|
||||
|
||||
return [
|
||||
|
||||
/*
|
||||
* 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.
|
||||
*/
|
||||
'description' => '',
|
||||
|
||||
|
||||
/*
|
||||
* 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 domains match this pattern (use * as a wildcard to match any characters). Example: 'api.*'.
|
||||
*/
|
||||
'domains' => ['*'],
|
||||
|
||||
/*
|
||||
* Match only routes whose paths match this pattern (use * as a wildcard to match any characters). Example: 'users/*'.
|
||||
*/
|
||||
'prefixes' => ['*'],
|
||||
|
||||
/*
|
||||
* [Dingo router only] Match only routes registered under this version. Wildcards are not supported.
|
||||
*/
|
||||
'versions' => ['v1'],
|
||||
],
|
||||
|
||||
/*
|
||||
* 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'],
|
||||
|
||||
/*
|
||||
* 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.
|
||||
*/
|
||||
'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,
|
||||
@@ -31,7 +155,7 @@ return [
|
||||
|
||||
/*
|
||||
* URL path to use for the docs endpoint (if `add_routes` is true).
|
||||
* By default, `/docs` opens the HTML page, and `/docs.json` downloads the Postman collection.
|
||||
* By default, `/docs` opens the HTML page, `/docs.postman` opens the Postman collection, and `/docs.openapi` the OpenAPI spec.
|
||||
*/
|
||||
'docs_url' => '/docs',
|
||||
|
||||
@@ -57,19 +181,19 @@ return [
|
||||
'enabled' => false,
|
||||
|
||||
/*
|
||||
* Set this to true if your API should be authenticated by default.
|
||||
* You can then use @unauthenticated or @authenticated on individual endpoints to change their status.
|
||||
* 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, query_or_body, basic, bearer, header (for custom header)
|
||||
* Options: query, body, basic, bearer, header (for custom header)
|
||||
*/
|
||||
'in' => 'bearer',
|
||||
|
||||
/*
|
||||
* The name of the parameter (eg token, key, apiKey) or header (eg Authorization, Api-Key).
|
||||
* The name of the auth parameter (eg token, key, apiKey) or header (eg Authorization, Api-Key).
|
||||
*/
|
||||
'name' => 'key',
|
||||
|
||||
@@ -82,7 +206,7 @@ return [
|
||||
|
||||
/*
|
||||
* Placeholder your users will see for the auth parameter in the example requests.
|
||||
* If this value is null, Scribe will use a random value.
|
||||
* Set this to null if you want Scribe to use a random value as placeholder instead.
|
||||
*/
|
||||
'placeholder' => '{YOUR_AUTH_KEY}',
|
||||
|
||||
@@ -106,9 +230,7 @@ INTRO
|
||||
/*
|
||||
* Example requests for each endpoint will be shown in each of these languages.
|
||||
* Supported options are: bash, javascript, php, python
|
||||
* You can add a language of your own, but you must publish the package's views
|
||||
* and define a corresponding view for it in the partials/example-requests directory.
|
||||
* See https://scribe.readthedocs.io/en/latest/generating-documentation.html
|
||||
* To add a language of your own, see https://scribe.readthedocs.io/en/latest/customization.html
|
||||
*
|
||||
*/
|
||||
'example_languages' => [
|
||||
@@ -117,25 +239,15 @@ INTRO
|
||||
],
|
||||
|
||||
/*
|
||||
* The base URL to be used in examples.
|
||||
* If this is null, Scribe will use the value of config('app.url').
|
||||
* The base URL to be used in examples. If this is empty, Scribe will use the value of config('app.url').
|
||||
*/
|
||||
'base_url' => null,
|
||||
|
||||
/*
|
||||
* The HTML <title> for the generated documentation, and the name of the generated Postman collection.
|
||||
* If this is null, Scribe will infer it from config('app.name').
|
||||
*/
|
||||
'title' => null,
|
||||
|
||||
'description' => '',
|
||||
|
||||
/*
|
||||
* Generate a Postman collection in addition to HTML docs.
|
||||
* 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.
|
||||
* Collection schema: https://schema.getpostman.com/json/collection/v2.0.0/collection.json
|
||||
*/
|
||||
'postman' => [
|
||||
'enabled' => true,
|
||||
@@ -149,7 +261,7 @@ INTRO
|
||||
],
|
||||
|
||||
/*
|
||||
* Generate an OpenAPI spec file in addition to docs webpage.
|
||||
* 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.
|
||||
@@ -187,129 +299,6 @@ INTRO
|
||||
*/
|
||||
'router' => 'laravel',
|
||||
|
||||
/*
|
||||
* The routes for which documentation should be generated.
|
||||
* 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 parsed in this group.
|
||||
* A route must fulfill ALL conditions to pass.
|
||||
*/
|
||||
'match' => [
|
||||
/*
|
||||
* Match only routes whose domains match this pattern (use * as a wildcard to match any characters). Example: 'api.*'.
|
||||
*/
|
||||
'domains' => ['*'],
|
||||
|
||||
/*
|
||||
* Match only routes whose paths match this pattern (use * as a wildcard to match any characters). Example: 'users/*'.
|
||||
*/
|
||||
'prefixes' => ['*'],
|
||||
|
||||
/*
|
||||
* (Dingo router only) Match only routes registered under this version.
|
||||
* Note that wildcards are not supported.
|
||||
*/
|
||||
'versions' => ['v1'],
|
||||
],
|
||||
|
||||
/*
|
||||
* Include these routes when generating documentation, 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 when generating documentation, even if they matched the rules above.
|
||||
* The route can be referenced by name or path here. Wildcards are supported.
|
||||
*/
|
||||
'exclude' => [
|
||||
// '/health', 'admin.*'
|
||||
],
|
||||
|
||||
/*
|
||||
* Specify rules to be applied to all the routes in this group when generating documentation
|
||||
*/
|
||||
'apply' => [
|
||||
/*
|
||||
* Specify 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,
|
||||
* we'll 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'],
|
||||
|
||||
/*
|
||||
* 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,
|
||||
],
|
||||
|
||||
/*
|
||||
* Cookies which should be sent with the API call.
|
||||
*/
|
||||
'cookies' => [
|
||||
// 'name' => 'value'
|
||||
],
|
||||
|
||||
/*
|
||||
* 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.
|
||||
*/
|
||||
'fileParams' => [
|
||||
// 'key' => '/home/me/image.png',
|
||||
],
|
||||
],
|
||||
],
|
||||
],
|
||||
],
|
||||
|
||||
/*
|
||||
* Configure how responses are transformed using @transformer and @transformerCollection (requires league/fractal package)
|
||||
*/
|
||||
'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,
|
||||
],
|
||||
|
||||
/*
|
||||
* If you would like the package to generate the same example values for parameters on each run,
|
||||
* set this to any number (eg. 1234)
|
||||
@@ -318,7 +307,7 @@ INTRO
|
||||
|
||||
/**
|
||||
* The strategies Scribe will use to extract information about your routes at each stage.
|
||||
* If you write or install a custom strategy, add it here. Unless you know what you're doing, you shouldn't remove any of the default strategies.
|
||||
* If you write or install a custom strategy, add it here.
|
||||
*/
|
||||
'strategies' => [
|
||||
'metadata' => [
|
||||
@@ -353,17 +342,26 @@ INTRO
|
||||
],
|
||||
|
||||
/*
|
||||
* [Advanced usage] If you would like to customize how routes are matched beyond the route configuration you may
|
||||
* Configure how responses are transformed using @transformer and @transformerCollection (requires league/fractal package)
|
||||
*/
|
||||
'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] If you would like to customize how routes are matched beyond the route configuration you may
|
||||
* declare your own implementation of RouteMatcherInterface
|
||||
*
|
||||
*/
|
||||
'routeMatcher' => \Knuckles\Scribe\Matching\RouteMatcher::class,
|
||||
|
||||
/**
|
||||
* [Advanced usage] If one of your app's database drivers does not support transactions,
|
||||
* [Advanced] If one of your app's database drivers does not support transactions,
|
||||
* docs generation (instantiating Eloquent models and making response calls) will likely fail.
|
||||
* To avoid that, you can add the driver class name here.
|
||||
* Be warned: that means all database changes will persist.
|
||||
* To avoid that, you can add the driver class name here. Be warned: that means all database changes will persist.
|
||||
*/
|
||||
'continue_without_database_transactions' => [],
|
||||
];
|
||||
|
||||
Reference in New Issue
Block a user