Version: Laravel: 4.x (current)

config/scribe.php

Here are the available options in the config/scribe.php file. They are roughly grouped into two: settings to customize the output, and settings to customize the extraction process.

tip

If you aren't sure what an option does, it's best to leave it set to the default.

Output settings

`theme`

The theme of the docs. Options:

When using static or laravel: default, elements (modelled after Stoplight Elements). See the theming guide.
When using external_static or external_laravel: scalar, elementsand rapidoc

Default: "default"

`type`

This is 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 within the resources/views/scribe folder, so you can add routing and authentication.
external_static and external_laravel do the same as above, but generate a basic template, passing the OpenAPI spec as a URL, allowing you to easily use the docs with an external generator.

Default: "static"

`static`

Settings for the static type output.

output_path: Output folder. The docs, Postman collection and OpenAPI spec will be placed in this folder. We recommend leaving this as public/docs, so people can access your docs through <your-app>/docs.
Default: "public/docs".

`external`

Settings for the external_static and external_laravel type output.

html_attributes: Any custom HTML attributes you wish to set. For instance, when using Stoplight Elements, you can pass any of the supported configuration options;

'external' => [
  'html_attributes' => [
    'hideSchemas' => 'true', # Note: values should be strings, not booleans
    'tryItCredentialsPolicy' => 'same-origin',
    'router' => 'history'
  ]
]

`laravel`

Settings for the laravel type output.

add_routes: Set this to true if you want the documentation endpoint (<your-app>/docs) to be automatically added to your app. To use your own routing, set this to false.
important
If you install this package with --dev, and you run composer install --no-dev in production, add_routes won't work in production.
Default: true
docs_url: The path for the documentation endpoint (if add_routes is true).
Default: "/docs".
assets_directory: 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}}
Default: null.
middleware: List of middleware to be attached to the documentation endpoint (if add_routes is true).

`base_url`

The base URL to be displayed in the docs. If you leave this empty, Scribe will use the current app URL (config('app.url')).

`title`

The HTML <title> for the generated documentation, and the name of the generated Postman collection and OpenAPI spec. If this is null, Scribe will infer it from config('app.name').

`description`

A description for your API. This will be placed in the "Introduction" section, before the intro_text. It will also be used as the info.description field in the generated Postman collection and OpenAPI spec.

`intro_text`

The text to place in the "Introduction" section (after the description). Markdown and HTML are supported.

`try_it_out`

Configure the API tester included in the docs.

enabled: Set this to true if you'd like Scribe to add a "Try It Out" button to your endpoints so users can test them from their browser.
Default: true.

important

For "Try It Out" to work, you'll need to make sure CORS is enabled on your endpoints.

base_url: The base URL where Try It Out requests should go to. For instance, you can set this to your staging server. Leave as null to use the current app URL (config(app.url)).
use_csrf: Fetch a CSRF token before each Try It Out request, and add it as an X-XSRF-TOKEN header to the request. This is needed if you're using Laravel Sanctum,.
Default: false.
csrf_url: The URL to fetch the CSRF token from (if use_csrf is true).
Default: '/sanctum/csrf-cookie'.

`logo`

Path to an image to use as your logo in the docs. This will be used as the value of the src attribute for the <img> tag, so make sure it points to a public URL or path accessible from your server.

If you're using a relative path, remember to make it relative to your docs output location (static type) or app URL (laravel type). For example, if your logo is in public/img:

for static type (output folder is public/docs), use '../img/logo.png'
for laravel type, use 'img/logo.png'

For best results, the image width should be 230px. Set this to false if you're not using a logo.

Default: false.

`last_updated`

Scribe shows a "Last updated" label in your docs. You can customize this label by specifying tokens and formats.

Available tokens are {date:<format>} and {git:<format>}.
The format you pass to date will be passed to PhP's date() function. See the docs for valid options.
The format you pass to git can be either "short" or "long", to get the short or long commit hash.

Examples:

Last updated: {date:F j, Y} 
// => Last updated: March 28, 2022
Last updated on {date:l, jS F} (Git commit {git:short}) 
// => Last updated on 28th March 2022 (Git commit ed8f2dd)

Default: "Last updated: {date:F j, Y}"

`groups`

`default`

When documenting your api, you use @group annotations to group API endpoints. Endpoints which do not have a group annotation will be grouped under the groups.default.

Default: "Endpoints".

`order`

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.

To describe an endpoint, follow the format '{method} /{path}' (for example, "POST /users").

Here's an example configuration:

'order' => [
   'This group will come first',
   'This group will come next' => [
       'POST /this-endpoint-will-come-first',
       'GET /this-endpoint-will-come-next',
   ],
   'This group will come third' => [
       'This subgroup comes first' => [
           'GET /this-other-endpoint-will-come-first',
           'GET /this-other-endpoint-will-come-next',
       ]
   ]
],

You can also bury a group. This can be achieved by specifying the group you want to be buried below the * character. Currently this is only supported for top level groups.

Here's an example configuration:

'order' => [
   'This group will come first',
   'This group will come next' => [
       'POST /this-endpoint-will-come-first',
       'GET /this-endpoint-will-come-next',
   ],
   '*', // this specifies the position of all unspecified groups
   'This group will always come last' => [
       'This subgroup comes first' => [
           'GET /this-other-endpoint-will-come-first',
           'GET /this-other-endpoint-will-come-next',
       ]
   ]
],

`examples`

Settings to customize how Scribe generates example values for your docs.

`faker_seed`

When generating examples for parameters, Scribe uses the fakerphp/faker package to generate random values. To generate the same example values each time, set this to any number (eg. 1234).

tip

Alternatively, you can set example values for parameters when documenting them.

`models_source`

With Eloquent 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's create()method, then its make() method, and if that fails, then try fetching the first from the database. You can reorder or remove strategies here.

Default: ['factoryCreate', 'factoryMake', 'databaseFirst']

`example_languages`

For each endpoint, an example request is shown in each of the languages specified in this array. Currently, only bash (curl), javascript (Fetch), php (Guzzle) and python (requests) are included. You can add extra languages, but you must also create the corresponding Blade view (see Adding more example languages).

Default: ["bash", "javascript"]

`postman`

Along with the HTML docs, Scribe can automatically generate a Postman collection for your API. This section is where you can configure or disable that.

For static output, the collection will be created in {static.output_path}/collection.json. For laravel output, the collection will be generated to storage/app/scribe/collection.json. Setting laravel.add_routes to true will add a /collection.json endpoint to fetch it.

enabled: Whether or not to generate a Postman API collection.
Default: true
overrides: Fields to merge with the collection after generating. Dot notation is supported. For instance, if you'd like to override the version in the info object, you can set overrides to ['info.version' => '2.0.0'].

`openapi`

Scribe can also generate an OpenAPI (Swagger) spec for your API. This section is where you can configure or enable that.

caution

The OpenAPI spec is an opinionated spec that doesn't cover all features of APIs in the wild (such as optional URL parameters). Scribe does its best, but there's no guarantee that the spec generated will exactly match your API structure.

For static output, the spec will be created in {static.output_path}/openapi.yaml. For laravel output, the spec will be generated to storage/app/scribe/openapi.yaml. Setting laravel.add_routes to true will add a /openapi.yaml endpoint to fetch it.

enabled: Whether or not to generate an OpenAPI spec.
Default: false
overrides: Fields to merge with the spec after generating. Dot notation is supported. For instance, if you'd like to override the version in the info object, you can set overrides to ['info.version' => '2.0.0'].

Extraction settings

`auth`

Specify authentication details about your API. This information will be used:

to derive the text in the "Authentication" section in the generated docs
to generate auth info in the Postman collection and OpenAPI spec
to add the auth headers/query parameters/body parameters to the docs and example requests
to set the auth headers/query parameters/body parameters for response calls

Here are the available settings:

enabled: Set this to true if any endpoints in your API use authentication.
Default: false.
default: Specify the default auth behaviour of your API.
If you set this to true, all your endpoints will be considered authenticated by default, and you can opt out individually with the @unauthenticated tag.
If you set this to false, your endpoints will not be authenticated by default, and you can turn on auth individually with the @authenticated tag.
Default: false.

caution

Even if you set auth.default, you must also set auth.enabled to true if you have at least one endpoint that is authenticated!

in: Where is the auth value meant to be sent in a request? Options:
- query (for a query parameter)
- body (for a body parameter)
- basic (for HTTP Basic auth via an Authorization header)
- bearer(for HTTP Bearer auth via an Authorization header)
- header (for auth via a custom header)
name: The name of the parameter (eg token, key, apiKey) or header (eg Authorization, Api-Key). When in is set to bearer or basic, this value will be ignored, and the header used will be Authorization.
use_value: 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 is empty, Scribe will use a randomly generated value. If you need to customize this value dynamically, you can use the beforeResponseCall() method.
placeholder: The placeholder your users will see for the auth parameter in the example requests. If this is empty, Scribe will generate a realistic-looking auth token instead (for example, "jh86fccvbAx6CmA9VS").
Default: "{YOUR_AUTH_KEY}".
extra_info: 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. This will be included in the Authentication section.

`strategies`

A nested array of strategies Scribe will use to extract information about your routes at each stage. If you write or install a custom strategy, add it here under the appropriate stage. By default, all strategies are enabled.

You can remove the strategies you don't need (for instance, you can remove the UseTransformerTags strategy if you aren't using transformers), add custom ones, or reorder them as you wish.

`routes`

The routes section is an array of items describing what routes in your application that should be included in the docs.

Each item in the routes array is a route group. A route group is an array containing:

rules defining what routes belong in that group (match, include, and exclude), and
any custom settings to apply to those routes (apply).

`match`

Let's start with the match section. This is where you tell Scribe the endpoints you want to document. The default looks like this:

config/scribe.php
'match' => [
  'prefixes' => ['api/*'],
  'domains' => ['*'],
],

This tells Scribe to match all routes starting with api/. So, for instance:

// 👍 Will match
Route::get('/api/users', [UserController::class, 'listUsers']);
Route::post('/api/users', [UserController::class, 'createUser']);

// ❌ Won't match
Route::get('/status', [StatusController::class, 'getStatus']);

tip

In route groups, * can often be used as a wildcard to mean "anything".

If you're using subdomain routing, you can also limit endpoints by domains. So, a config like this:

'match' => [
  'prefixes' => ['api/*'],
  'domains' => ['v2.acme.co'],
],

// Results:

// 👍 Will match
Route::group(['domain' => 'v2.acme.co'], function () {
  Route::get('/api/users', [UserController::class, 'listUsers']);
  Route::post('/api/users', [UserController::class, 'createUser']);
});

// ❌ Won't match
Route::get('/api/getUsers', [UserControllerV::class, 'listUsers']);

Finally, if you're using Dingo, you can also limit the versions you want to match (no wildcards are not supported).

'match' => [
  'prefixes' => ['api/*'],
  'domains' => ['v2.acme.co'],
  'versions' => ['v2'],
],

// 👍 Will match
$api->version('v2', function (Router $api) {
    $api->post('/api/users');
});
$api->version('v1', function (Router $api) {
    // 👍 Won't match
});

`include` and `exclude`

include and exclude allow you to override match. With include, you can add routes to the group, even if they didn't match. With exclude, you can remove routes that matched. Both of these take a list of route names or paths.

For example:

'match' => [
  'domains' => ['v2.acme.co'],
  'prefixes' => ['*'],
],
'include' => ['public.metrics'],
'exclude' => ['internal/*'],


Route::group(['domain' => 'v2.acme.co'], function () {
  // 👍 Will match
  Route::get('/api/users', [UserController::class, 'listUsers']);
  Route::post('/api/users', [UserController::class, 'createUser']);
  // ❌ Matches, but excluded by `exclude`
  Route::get('/internal/users', [InternalController::class, 'listUsers']);
  Route::post('/internal/check', [InternalController::class, 'checkThings']);
});

// 👍 Doesn't match, but included by `include`
Route::get('/metrics', [PublicController::class, 'showMetrics'])
  ->name('public.metrics');

// ❌ Won't match
Route::get('/api/getUsers', [UserControllerV!::class, 'listUsers']);

`apply`

The apply section of the route group is where you specify any additional settings to be applied to those routes when generating documentation. There are a number of settings you can tweak here:

headers: Any headers you specify here will be added in example requests and response calls. Headers are specified as key => value strings.
response_calls: These are the settings that will be applied when making "response calls".

config/scribe.php
'response_calls' => [
    'methods' => ['GET'],
    'config' => [
        'app.env' => 'documentation',
    ],
    'queryParams' => [
        // 'key' => 'value',
    ],
    'bodyParams' => [
        // 'key' => 'value',
    ],
    'fileParams' => [
        // 'key' => 'storage/app/image.png',
    ],
],

The methods key determines what endpoints allow response calls. By default, Scribe will only try response calls for GET endpoints, but you can change this as you wish. Set it to ['*'] to mean all methods. Leave it as an empty array to turn off response calls for that route group.
The queryParams, bodyParams, and fileParams keys allow you to set specific data to be sent in response calls. For file parameters, each value should be a valid path (absolute or relative to your project directory) to a file on the machine.
The config key allows you to customise your Laravel app's config for the response call.

tip

By splitting your routes into groups, you can apply different settings to different routes.

`fractal`

This section only applies if you're using transformers for your API (via the league/fractal package), and documenting responses with @transformer and @transformerCollection. Here, you configure how responses are transformed.

serializer: If you are using a custom serializer with league/fractal, you can specify it here. Leave this as null to use no serializer or return a simple JSON.
Default: null

`database_connections_to_transact`

To avoid modifying your database, Scribe can run response calls and example model creation (API resource and Transformer strategies) in a database transaction, and then roll it back afterwards. This item is where you specify which database connections Scribe can run transactions for.

By default, this is set to your default database connection (config('database.default')), so if you only use one database connection, you should be fine. If you use multiple connections, you should add them to the array. For example:

config/scribe.php
'database_connections_to_transact' => [
    config('database.default'),
    'pgsql',
],

`routeMatcher`

The route matcher class is responsible for fetching the routes to be documented. The default matcher is the included \Knuckles\Scribe\Matching\RouteMatcher, but you can provide your own custom implementation if you wish. The provided matcher should implement \Knuckles\Scribe\Matching\RouteMatcherInterface.

tip

Output settings​

theme​

type​

static​

external​

laravel​

important

base_url​

title​

description​

intro_text​

try_it_out​

important

logo​

last_updated​

groups​

default​

order​

examples​

faker_seed​

tip

models_source​

example_languages​

postman​

openapi​

caution

Extraction settings​

auth​

caution

strategies​

routes​

match​

tip

include and exclude​

apply​

tip

fractal​

database_connections_to_transact​

routeMatcher​

Output settings

`theme`

`type`

`static`

`external`

`laravel`

`base_url`

`title`

`description`

`intro_text`

`try_it_out`

`logo`

`last_updated`

`groups`

`default`

`order`

`examples`

`faker_seed`

`models_source`

`example_languages`

`postman`

`openapi`

Extraction settings

`auth`

`strategies`

`routes`

`match`

`include` and `exclude`

`apply`

`fractal`

`database_connections_to_transact`

`routeMatcher`