Adding general information about your API¶
Attention
These docs are for Scribe v2, which is no longer maintained. See scribe.knuckles.wtf/laravel for Scribe v3.
Authentication information¶
You can add authentication information for your API using the auth
section in scribe.php
.
Important
Scribe uses your specified authentication information in three places:
- Generating an “Authentication” section in your docs
- Adding authentication parameters to your example requests for endpoints marked as
@authenticated
(or if you have withauth.default
= true) - Adding the necessary auth parameters with the specified value to response calls only for endpoints marked as
@authenticated
(or if you have withauth.default
= true)
Here’s how you’d configure auth with a query parameter named apiKey
:
'auth' => [
'enabled' => true,
'default' => false,
'in' => 'query',
'name' => 'apiKey',
'use_value' => env('SCRIBE_API_KEY'),
'placeholder' => 'YOUR-API-KEY',
'extra_info' => 'You can retrieve your key by going to settings and clicking <b>Generate API key</b>.',
],
If apiKey
were to be a body parameter, the config would be same. Just set in
to 'body'
.
Here’s an example with a bearer token (also applies to basic auth, if you change in
to 'basic'
):
'auth' => [
'enabled' => true,
'default' => false,
'in' => 'bearer',
'name' => 'hahaha', // <--- This value is ignored for bearer and basic auth
'use_value' => env('SCRIBE_AUTH_KEY'),
'placeholder' => '{ACCESS_TOKEN}',
'extra_info' => 'You can retrieve your token by visiting your dashboard and clicking <b>Generate API token</b>.',
],
And here’s an example with a custom header:
'auth' => [
'enabled' => true,
'default' => false,
'in' => 'header',
'name' => 'Api-Key', // <--- The name of the header
'use_value' => env('SCRIBE_AUTH_KEY'),
'placeholder' => 'YOUR-API-KEY',
'extra_info' => 'You can retrieve your token by visiting your dashboard and clicking <b>Generate API token</b>.',
],
The default
field is the default behaviour of our API. If your endpoints are authenticated by default, set this to true
, then use @unauthenticated
on the method doc block if you need to turn off auth for specific endpoints. If your endpoints are open by default, leave this as false
, then use @authenticated
on the method doc block if you need to turn on auth for specific endpoints.
You can set whatever you want as the extra_info
. A good idea would be to tell your users where to get their auth key.
The use_value
field is only used by Scribe for response calls. It won’t be included in the generated output or examples.
The placeholder
is the opposite of use_value
. It will be used only as a placeholder in the generated example requests.
For more information, see the reference documentation on the auth section.
Introductory text¶
The intro_text
key in scribe.php
is where you can set the text shown to readers in the “Introduction” section. If your text is too long to be put in a config file, you can create a prepend.md
containing the intro text and put it in the resources/docs
folder.
Title¶
You can set the HTML <title>
for the generated docs webpage, Postman collection and OpenAPI spec by setting the title
key in scribe.php
. If you leave it as null, Scribe will infer it from the value of config('app.name')
.
Logo¶
Maybe you’ve got a pretty logo for your API or company, and you’d like to display that on your documentation page. No worries! To add a logo, set the logo
key in scribe.php
to the path of the logo. Here are your options:
- To point to an image on an external public URL, set
logo
to that URL. - To point to an image in your codebase, set
logo
to thepublic_path()
of the image, if you’re usinglaravel
type docs. If you’re usingstatic
type, pass in the relative path to the image from thepublic/docs
directory. For example, if your logo is in public/images, use ‘../img/logo.png’ forstatic
type and ‘img/logo.png’ forlaravel
type. - To disable the logo, set
logo
to false.