### Start the Project

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/CONTRIBUTING.md

Run the project after dependencies are installed. This command starts the development server or the main application.

```bash
yarn start
```

--------------------------------

### Example Route Matching

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/reference/10-config.md

Illustrates which routes will be matched based on the configured 'match' settings. Routes starting with 'api/' are included, while others are excluded.

```php
// 👍 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']);
```

--------------------------------

### Install Node.js

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/CONTRIBUTING.md

Ensure Node.js is installed on your system. This is a prerequisite for running the project.

```bash
Install Node.js
```

--------------------------------

### Example Settings Array

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/advanced/40-writing-plugins.mdx

An example of the settings array that a strategy might receive when configured with `wrapWithSettings`.

```php
  [
     'paginationType' => 'cursor'
  ],
```

--------------------------------

### Bootstrap Hook Example

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/50-hooks.md

Use the bootstrap hook to run code when the generate command starts. The callback receives the GenerateDocumentation command instance. Always wrap in class_exists.

```php
use Knuckles\Scribe\Commands\GenerateDocumentation;
use Knuckles\Scribe\Scribe;
use Event;

public function boot()
{
  if (class_exists(\Knuckles\Scribe\Scribe::class)) {
    Scribe::bootstrap(function (GenerateDocumentation $command) {
        Event::fake();
    });
  }
}
```

--------------------------------

### Specify Example Values for Parameters

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/documenting/50-query-body-parameters.mdx

Add `Example: <your-example>` to the end of a parameter description to use a specific value in generated examples.

```php
/**
 * @queryParam sort Field to sort by. Defaults to 'id'. Example: published_at
 * @queryParam fields required Comma-separated fields to include in the response. Example: title,published_at,id
 * @queryParam filters[published_at] Filter by date published. No-example
*/
#[QueryParam("filters[title]", "Filter by title.", required: false, example: "No-example")]
public function endpoint()
```

--------------------------------

### Install Dependencies with Yarn

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/README.md

Use this command to install project dependencies. Ensure you have Yarn installed.

```console
yarn install
```

--------------------------------

### Publish Scribe Example Requests

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/advanced/50-theming.mdx

Run this command to publish only the example request templates.

```bash
php artisan vendor:publish --tag=scribe-examples
```

--------------------------------

### Specifying Examples and Omitting Parameters

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/nodejs/documenting/50-query-body-parameters.mdx

Control how parameters appear in examples. Use 'Example:' to provide a specific value or 'No-example' to omit optional parameters from examples.

```javascript
/**
 * @queryParam {string} sort Field to sort by. Defaults to 'id'. Example: published_at
 * @queryParam {string} fields required Comma-separated fields to include in the response. Example: title,published_at,id
 * @queryParam {string} filters[published_at] Filter by date published. No-example
 * @queryParam {string} filters[title] Filter by title. No-example
*/
```

--------------------------------

### Example JSON file content

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/nodejs/documenting/60-responses.md

This is an example of the content that can be placed in a file referenced by `@responseFile`.

```json
{"id":4,"name":"Jessica Jones"}
```

--------------------------------

### Install Regular Laravel Dependencies

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/120-contributing.md

Run this command to install the standard Laravel dependencies for the project.

```bash
composer install
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/CONTRIBUTING.md

Install all necessary project dependencies using Yarn. This command should be run in the project directory.

```bash
yarn
```

--------------------------------

### Docusaurus Configuration Example

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/README.md

Example configuration for managing different versions of Laravel documentation within Docusaurus.

```javascript
current: {
    label: "Laravel: 6.x (current)",
    badge: true,
},
"4.x": {
  label: "Laravel: 5.x",
  badge: true,
  banner: 'unmaintained',
  path: '/5.x',
}
```

--------------------------------

### Query Parameters Example

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/nodejs/documenting/50-query-body-parameters.mdx

Example of documenting query parameters using the @queryParam annotation.

```APIDOC
## GET /api/items

### Description
This endpoint retrieves a list of items with sorting, filtering, and field selection.

### Method
GET

### Endpoint
/api/items

### Parameters
#### Query Parameters
- **sort** (string) - Optional - Field to sort by. Defaults to 'id'. Example: published_at
- **fields** (string) - Required - Comma-separated list of fields to include in the response. Example: title,published_at,id
- **filters[published_at]** (string) - Optional - Filter by date published. No-example
- **filters[title]** (string) - Optional - Filter by title. No-example
- **filters[is_public]** (integer) - Optional - Filter by whether a post is public or not. Example: 1

### Request Example
```
/api/items?sort=published_at&fields=title,published_at,id&filters[published_at]=2023-01-01&filters[is_public]=1
```

### Response
#### Success Response (200)
- **items** (array) - List of items.
- **meta** (object) - Metadata about the response.
```

--------------------------------

### Body Parameters Example

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/nodejs/documenting/50-query-body-parameters.mdx

Example of documenting body parameters using the @bodyParam annotation.

```APIDOC
## POST /api/example

### Description
This endpoint demonstrates the usage of body parameters.

### Method
POST

### Endpoint
/api/example

### Parameters
#### Request Body
- **user_id** (integer) - Required - The id of the user. Example: 9
- **room_id** (string) - Optional - The id of the room.
- **forever** (boolean) - Optional - Whether to ban the user forever. Example: false
- **another_one** (number) - Optional - This won't be added to the examples. No-example

### Request Example
```json
{
  "user_id": 9,
  "room_id": "some_room_id",
  "forever": false,
  "another_one": 123.45
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
```

--------------------------------

### Ruby Example Request Template

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/advanced/20-example-requests.mdx

This Blade template generates a Ruby example request using the `$baseUrl` and `$endpoint` variables. It handles body parameters, headers, and constructs a `RestClient` request. Ensure you have the `rest-client` gem installed.

```html
@php
    // Adding this so we get IDE code completion for $endpoint
    /** @var \Knuckles\Camel\Output\OutputEndpointData $endpoint */
@endphp
```ruby

require 'rest-client'

@if(!empty($endpoint->cleanBodyParameters))
body = {!! json_encode($endpoint->cleanBodyParameters, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE) !!}
@endif
@if(!empty($endpoint->headers))
headers = {
@foreach($endpoint->headers as $header => $value)
    "{{$header}}": "{{$value}}",
@endforeach
}
@endif

response = RestClient.{{strtolower($endpoint->httpMethods[0])}}(
  '{{ $baseUrl }}/{{ $endpoint->boundUri }}'@if(!empty($endpoint->cleanBodyParameters)),
  body @endif
@if(!empty($endpoint->headers)),
  headers
@endif
)

p response.body

```
```

--------------------------------

### Response Example Annotations

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/nodejs/reference/20-annotations.md

Use `@response` to provide example responses, optionally specifying a status code and scenario. The response body follows.

```text
@response {"a": "b"}
```

```text
@response 201 {"a": "b"}
```

```text
@response 201 {"a": "b"} scenario="Operation successful"
```

```text
@response status=201 scenario="Operation successful" {"a": "b"}
```

```text
@response scenario=Success {"a": "b"}
```

```text
@response 201 scenario="Operation successful" {"a": "b"}
```

--------------------------------

### Specifying and Omitting Examples

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/documenting/50-query-body-parameters.mdx

Control how examples are generated for your API parameters. You can provide specific example values or choose to omit parameters from examples entirely.

```APIDOC
## Query Parameters with Custom Examples and Omissions

### Description
Demonstrates how to set default values, provide specific examples, and omit optional parameters from examples for query parameters.

### Method
GET (example)

### Endpoint
/example

### Parameters
#### Query Parameters
- **sort** (string) - Optional - Field to sort by. Defaults to 'id'. Example: published_at
- **fields** (string[]) - Required - Comma-separated fields to include in the response. Example: title,published_at,id
- **filters[published_at]** (string) - Optional - Filter by date published. No-example

### Request Example
```json
{
  "sort": "published_at",
  "fields": "title,published_at,id"
}
```

### Response
#### Success Response (200)
- **message** (string) - A success message.

#### Response Example
```json
{
  "message": "Example response"
}
```
```

```APIDOC
## Body Parameters with Custom Examples and Omissions

### Description
Illustrates how to define complex body parameters including objects and arrays, with custom examples and omission rules.

### Method
POST (example)

### Endpoint
/example

### Parameters
#### Request Body
- **user** (object) - Required - The user details
  - **user.name** (string) - Required - The user's name
  - **user.age** (string) - Required - The user's age
- **friend_ids** (int[]) - Optional - List of the user's friends.
- **cars** (object[]) - Optional - List of cars
  - **cars[].year** (string) - Optional - The year the car was made. Example: 1997
  - **cars[].make** (string) - Optional - The make of the car. Example: Toyota

### Request Example
```json
{
  "user": {
    "name": "John Doe",
    "age": "30"
  },
  "friend_ids": [1, 2, 3],
  "cars": [
    {
      "year": "1997",
      "make": "Toyota"
    }
  ]
}
```

### Response
#### Success Response (200)
- **status** (string) - The status of the operation.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Returning URL or Query Parameters

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/reference/30-plugin-api.md

Example of defining a URL or query parameter with its type, description, example, and required status.

```php
return [
  'room_id' => [
    'type' => 'string',
    'description' => '',
    'example' => 'r4oiu78t63ns3',
    'required' => true, 
  ]
];
```

--------------------------------

### Custom Routes for Multiple Docs

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/tasks/10-generating.md

Example of how to add custom routes in `routes/web.php` to serve multiple sets of generated documentation.

```php
Route::view('/docs', 'scribe.index')->name('scribe');
Route::view('/admin/docs', 'scribe_admin.index')->name('scribe-admin');

```

--------------------------------

### Get Application Routes

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/98-architecture.md

Fetches all application routes and filters them based on configuration. This is the first step in the documentation generation process.

```php
$routes = $routeMatcher->getRoutes($yourConfig);
```

--------------------------------

### Documenting URL Parameters with @urlParam

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/nodejs/documenting/40-url-parameters.md

Use the @urlParam annotation to define the type, name, required status, and description for URL parameters. Append 'Example: <your-example>' to provide a custom example value.

```javascript
/**
 * @urlParam {integer} id required The ID of the post.
 * @urlParam {string} lang The language. Example: en
 */
app.get("/post/:id/:lang?", (req, res) => {...});
```

--------------------------------

### Pagination with API Resources

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/documenting/60-responses.mdx

Examples of how to configure pagination for API resource responses.

```APIDOC
## GET /more-users

### Description
Lists users with standard pagination.

### Method
GET

### Endpoint
/more-users

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "message": "This is a placeholder request"
}
```

### Response
#### Success Response (200)
- **data** (array) - A list of users.
  - **id** (integer) - The user's ID.
- **links** (object) - Pagination links.
- **meta** (object) - Pagination metadata.

#### Response Example
```json
{
  "data": [
    {
      "id": 1
    }
  ],
  "links": {
    "first": "...",
    "last": "..."
  },
  "meta": {
    "current_page": 1,
    "per_page": 10
  }
}
```
```

```APIDOC
## GET /more-users

### Description
Lists users with simple pagination.

### Method
GET

### Endpoint
/more-users

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "message": "This is a placeholder request"
}
```

### Response
#### Success Response (200)
- **data** (array) - A list of users.
  - **id** (integer) - The user's ID.
- **links** (object) - Pagination links (next/prev).

#### Response Example
```json
{
  "data": [
    {
      "id": 1
    }
  ],
  "links": {
    "next": "...",
    "prev": "..."
  }
}
```
```

```APIDOC
## GET /more-users

### Description
Lists users with cursor-based pagination.

### Method
GET

### Endpoint
/more-users

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "message": "This is a placeholder request"
}
```

### Response
#### Success Response (200)
- **data** (array) - A list of users.
  - **id** (integer) - The user's ID.
- **links** (object) - Pagination links (next/prev cursors).

#### Response Example
```json
{
  "data": [
    {
      "id": 1
    }
  ],
  "links": {
    "next": "...",
    "prev": "..."
  }
}
```
```

--------------------------------

### Full Scribe Authentication Configuration Example

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/documenting/1-api-information.mdx

A comprehensive example of Scribe's authentication configuration, including settings for default behavior, token usage, placeholders, and extra informational text for users.

```php
return [
  // ...
  'auth' => [
    'enabled' => true,
    'default' => false,
    'in' => 'bearer',
    'name' => 'Authorization',
    '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>.',
  ],
];
```

--------------------------------

### Returning Body Parameters with Custom Data

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/reference/30-plugin-api.md

Example of defining a body parameter, including custom data like format, and specifying if it's required and its example value.

```php
return [
  'submission_date' => [
    'type' => 'string',
    'example' => '2021-02-03T01:00:00Z',
    'required' => true, 
    'custom' => [
      'format' => 'datetime'
    ]
  ]
];
```

--------------------------------

### Generate Docs for Express

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/nodejs/40-generating-documentation.md

Use this command for Express projects, specifying your app file. An example is provided.

```sh
npx scribe generate -a <your-app-file>

# Example:
# npx scribe generate -a app.js
```

--------------------------------

### URL Parameter Annotations

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/nodejs/reference/20-annotations.md

Use `@urlParam` to define URL parameters. Specify type, name, whether it's required, a description, and an optional example. Append 'No-example' to omit from examples.

```text
@urlParam {int} id
```

```text
@urlParam {int} id required
```

```text
@urlParam {int} id The user's ID.
```

```text
@urlParam {int} id The user's ID. Example: 88683
```

```text
@urlParam {int} id Example: 88683
```

```text
@urlParam {int} id required The user's ID. Example: 88683
```

```text
@urlParam {int} id The user's ID. No-example
```

--------------------------------

### Describe Query Parameters with Tags

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/reference/20-annotations.md

Use tags to describe query parameters. Specify type, required status, description, and examples. Use 'Enum:' for allowed values and 'No-example' to exclude from examples.

```php
@queryParam date The date. Example: 2022-01-01
@queryParam language The language. Enum: en, de, fr
@queryParam language The language. Enum: en, de, fr. Example: en
@queryParam page int
@queryParam page int The page number.
@queryParam page int required The page number. Example: 4
@queryParam page int The page number. No-example
```

--------------------------------

### Returning Headers

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/reference/30-plugin-api.md

Example of returning custom headers and their values from a strategy. `null` can be used for headers with no specific value.

```php
return [
  'Api-Version' => null,
  'Content-Type' => 'application/xml',
];
```

--------------------------------

### Generate Docs for Restify

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/nodejs/40-generating-documentation.md

For Restify projects, use this command and specify your server file. An example is included.

```sh
npx scribe generate -s <your-server-file>

# Example:
# npx scribe generate -s server.js
```

--------------------------------

### Returning Responses

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/reference/30-plugin-api.md

Example of defining a response, including its status code, headers, description, and content.

```php
return [
  [
    'status' => 201,
    'headers' => ['sample-header' => 'sample-value'],
    'description' => 'Operation successful.',
    'content' => '{"room": {"id": "r4oiu78t63ns3"}}',
  ],
];
```

--------------------------------

### URL Parameter Attribute Examples

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/reference/20-annotations.md

Describes URL parameters using the #[UrlParam] attribute. Various formats are shown for name, type, description, required status, enums, and examples.

```php
#[UrlParam("id")]
#[UrlParam("id", "int")]
#[UrlParam("id", "int")]
#[UrlParam("id", "int", "The user's ID.")]
#[UrlParam("id", "int", "The user's ID.", example: 88683)]
#[UrlParam("language", "The language.", enum: ["en", "de", "fr"])]
#[UrlParam("language", "The language.", enum: SupportedLanguage::class)]
#[UrlParam("language", "The language.", enum: SupportedLanguage::class, example: "en")]
#[UrlParam("id", "int", "The user's ID.", required: false, example: 88683)]
#[UrlParam("id", "int", "The user's ID.", required: false, example: "No-example")]
public function endpoint() {...}
```

--------------------------------

### URL Parameter Tag Examples

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/reference/20-annotations.md

Describes URL parameters using the @urlParam tag. Various formats are shown for name, type, required status, description, enums, and examples.

```php
@urlParam id
@urlParam id int
@urlParam id int required
@urlParam id int required The user's ID.
@urlParam language The language. Enum: en, de, fr
@urlParam language The language. Enum: en, de, fr. Example: en
@urlParam id int required The user's ID. Example: 88683
@urlParam id int The user's ID. Example: 88683
@urlParam id int The user's ID. No-example
```

--------------------------------

### Describe Body and Query Parameters with PHP Annotations

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/documenting/50-query-body-parameters.mdx

Use `@bodyParam` and `@queryParam` tags within your method's docblock to define parameters. The type is optional for `@queryParam` and defaults to string if not specified. Examples can be provided using the `Example:` keyword.

```php
/**
* @bodyParam user_id int required The id of the user. Example: 9
* @bodyParam room_id string The id of the room.
* @bodyParam forever boolean Whether to ban the user forever. Example: false
* @bodyParam another_one number This won't be added to the examples. No-example
*/
public function updateDetails()
{
}
```

```php
/**
 * @queryParam sort string Field to sort by. Defaults to 'id'.
 * @queryParam fields required Comma-separated list of fields to include in the response. Example: title,published_at,is_public
 * @queryParam filters[published_at] Filter by date published.
 * @queryParam filters[is_public] integer Filter by whether a post is public or not. Example: 1
 */
public function listPosts()
{
    // ...
}
```

--------------------------------

### Enable Corepack

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/CONTRIBUTING.md

Enable Corepack to manage package manager versions. No separate Yarn installation is needed.

```bash
corepack enable
```

--------------------------------

### API Resource Annotations (Tags)

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/documenting/60-responses.mdx

Examples using the `@apiResource` and `@apiResourceModel` annotations to specify resource classes and models.

```APIDOC
## GET /users/{user}

### Description
Retrieves a specific user using an API resource.

### Method
GET

### Endpoint
/users/{user}

### Parameters
#### Path Parameters
- **user** (integer) - The ID of the user to retrieve.

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "message": "This is a placeholder request"
}
```

### Response
#### Success Response (200)
- **id** (integer) - The user's ID.

#### Response Example
```json
{
  "id": 1
}
```
```

```APIDOC
## GET /users

### Description
Lists all users using an API resource collection.

### Method
GET

### Endpoint
/users

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "message": "This is a placeholder request"
}
```

### Response
#### Success Response (200)
- **data** (array) - A list of users.
  - **id** (integer) - The user's ID.

#### Response Example
```json
{
  "data": [
    {
      "id": 1
    },
    {
      "id": 2
    }
  ]
}
```
```

```APIDOC
## GET /more-users

### Description
Lists more users using a specific resource collection class.

### Method
GET

### Endpoint
/more-users

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "message": "This is a placeholder request"
}
```

### Response
#### Success Response (200)
- **data** (array) - A list of users.
  - **id** (integer) - The user's ID.

#### Response Example
```json
{
  "data": [
    {
      "id": 1
    },
    {
      "id": 2
    }
  ]
}
```
```

--------------------------------

### GET /listPosts

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/documenting/50-query-body-parameters.mdx

Example of using @queryParam annotations to define query parameters for an endpoint.

```APIDOC
## GET /listPosts

### Description
Retrieves a list of posts, with options for sorting, filtering, and field selection.

### Method
GET

### Endpoint
/listPosts

### Parameters
#### Query Parameters
- **sort** (string) - Optional - Field to sort by. Defaults to 'id'.
- **fields** (string) - Required - Comma-separated list of fields to include in the response. Example: title,published_at,is_public
- **filters[published_at]** (string) - Optional - Filter by date published.
- **filters[is_public]** (integer) - Optional - Filter by whether a post is public or not. Example: 1

### Request Example
```
/listPosts?sort=created_at&fields=title,content&filters[is_public]=1
```

### Response
#### Success Response (200)
- **data** (array) - List of posts.
- **meta** (object) - Metadata about the response.

#### Response Example
```json
{
  "data": [
    {
      "title": "Example Post",
      "content": "This is the content of the example post."
    }
  ],
  "meta": {
    "total": 10
  }
}
```
```

--------------------------------

### Build Production Version

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/README.md

Creates a production-ready build of the documentation site.

```console
yarn build
```

--------------------------------

### Set API Description and Intro Text

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/documenting/1-api-information.mdx

Configure the 'description' for a general API overview and 'intro_text' for the content displayed in the 'Introduction' section. Markdown and HTML are supported. The intro text is a HEREDOC example.

```php
'description' => 'Start (and never finish) side projects with this API.',
  'intro_text' => <<<INTRO
This documentation will 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
```

--------------------------------

### Configure Global Headers in .scribe.config.js

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/nodejs/documenting/30-headers.md

Define headers for multiple endpoints by using the `apply.headers` section in your `.scribe.config.js` file. This example applies the `Api-Version: v2` header to all routes starting with `v2/`.

```javascript
  routes: [
    {
        include: ['v2/*'],
        exclude: [],
        apply: {
            headers: {'Api-Version': 'v2'}
        }
    }
  ]
```

--------------------------------

### Implement Strategy Logic for Pagination Parameters

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/advanced/40-writing-plugins.mdx

This code snippet shows how to implement the __invoke method to extract pagination parameters for GET requests that appear to be index routes. It defines 'page' and 'pageSize' parameters, with 'pageSize' configured to be omitted from examples.

```php
public function __invoke(ExtractedEndpointData $endpointData, array $settings = []): ?array
{
    $isGetRoute = in_array('GET', $endpointData->httpMethods);
    $isIndexRoute = strpos($endpointData->route->getName(), '.index') !== false;
    if ($isGetRoute && $isIndexRoute) {
        return [
            'page' => [
                'description' => 'Page number to return.',
                'required' => false,
                'example' => 1,
            ],
            'pageSize' => [
                'description' => 'Number of items to return in a page. Defaults to 10.',
                'required' => false,
                'example' => null, // We don't want it to show in examples
            ],
        ];
    }

    return null;
}
```

--------------------------------

### Set API Description and Intro Text

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/nodejs/documenting/1-api-information.md

Configure the `description` for the API's "Introduction" section and `introText` for additional introductory content. Markdown and HTML are supported.

```javascript
description: 'Start (and never finish) side projects with this API.',
  introText: '
This documentation will 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>
',
```

--------------------------------

### Version Documentation

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/README.md

Pins the current documentation as an old version. Replace '5.x' with the desired old version number.

```console
yarn run docusaurus docs:version:laravel 5.x 
```

--------------------------------

### Basic Custom Theme Structure (Blade/HTML)

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/advanced/50-theming.mdx

This is a minimal example of a custom theme's `index.blade.php` file. It sets up the basic HTML structure, includes necessary CSS and JS for styling and syntax highlighting, and outputs introduction and authentication content. It falls back to the default theme for rendering endpoints.

```html
<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">
    <title>{!! $metadata['title'] !!}</title>

    <link rel="stylesheet" href="../docs/css/nasty.css">

    <link rel="stylesheet"
          href="//unpkg.com/@highlightjs.cdn-assets@10.7.2/styles/obsidian.min.css">
    <script src="//unpkg.com/@highlightjs.cdn-assets@10.7.2/highlight.min.js"></script>
    <script>hljs.highlightAll();</script>
</head>

<body>
    <div class="content">
        {!! $intro !!}

        {!! $auth !!}

        @include("scribe::themes.default.groups")
    </div>
</body>
</html>
```

--------------------------------

### Install Scribe v2 Package

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/nodejs/20-migrating-v3.md

Upgrade the Scribe package to version 2.0 or higher and install dependencies.

```bash
npm i
```

--------------------------------

### Serve Production Build Locally

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/README.md

Serves the production build on localhost:3000 for testing.

```console
yarn serve
```

--------------------------------

### Using Scribe Configuration Helpers

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/20-migrating.mdx

Demonstrates the use of new constants and helpers to configure Scribe strategies, including defaults, exclusions, and custom additions. Ensure Scribe is in 'require' if using in production to avoid runtime errors.

```php
use Knuckles\Scribe\Config\Defaults;
use function Knuckles\Scribe\Config\{removeStrategies, configureStrategy};

  'strategies' => [
    'metadata' => [
       // I want to use the defaults
      ...Defaults::METADATA_STRATEGIES,
    ],
    'headers' => [
      // I want the defaults, except for some.
      ...removeStrategies(
        Defaults::HEADERS_STRATEGIES,
        [Strategies\Headers\GetFromHeaderTag::class]
      )
    ],
    'urlParameters' => [
      // I want the defaults, plus my own strategy.
      ...Defaults::URL_PARAMETERS_STRATEGIES,
      App\Docs\Strategies\SomeCoolStuff::class,
    ],
    'queryParameters' => [
      // I want the defaults, plus my own strategy, but only on some endpoints
      ...Defaults::QUERY_PARAMETERS_STRATEGIES,
      // `wrapWithSettings` works on any strategy, inbuilt or custom
      App\Docs\Strategies\SomeCoolStuff::wrapWithSettings(
        only: ['POST /cool/*'],
      ),
    ],
    'bodyParameters' => [
      ...Defaults::BODY_PARAMETERS_STRATEGIES,
      // I want the defaults, plus my own strategy, but excluding some endpoints
      App\Docs\Strategies\SomeCoolStuff::wrapWithSettings(
        except: ['POST /uncool'],
      ),
    ],
    // I want the defaults, but I need to adjust the settings on one of them
    'responses' => configureStrategy(
      Defaults::RESPONSES_STRATEGIES,
      Strategies\Responses\ResponseCalls::withSettings(
        only: ['GET *'],
        config: [
            'app.debug' => false,
        ]
      )
      ),
    'responseFields' => [
      ...Defaults::RESPONSE_FIELDS_STRATEGIES,
    ],
]
```

```php
Strategies\StaticData::withSettings(data: [
  'Accept' => 'application/json',
]),

[
  Strategies\StaticData::class,
  [
    'data' => ['Accept' => 'application/json']
  ]
]
```

```php
Strategies\Responses\ResponseCalls::withSettings(
  only: [], except: ['*'],
)
```

--------------------------------

### Install Scribe for Restify

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/nodejs/0-intro.mdx

Install the Scribe package for Restify using npm. This command adds the necessary package to your project dependencies.

```sh
npm i @knuckleswtf/scribe-restify
```

--------------------------------

### Create New Docs Version

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/CONTRIBUTING.md

Instructions for creating a new version of the documentation. Refer to the README file for detailed steps.

```markdown
See the README
```

--------------------------------

### Initialize Scribe Configuration

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/nodejs/getting-started/1-adonis.md

Generate the Scribe configuration file by running the ace command.

```bash
node ace scribe:init
```

--------------------------------

### Install Scribe for Express

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/nodejs/0-intro.mdx

Install the Scribe package for Express using npm. This command adds the necessary package to your project dependencies.

```sh
npm i @knuckleswtf/scribe-express
```

--------------------------------

### Install Scribe for AdonisJS

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/nodejs/0-intro.mdx

Install the Scribe package for AdonisJS using npm. This command adds the necessary package to your project dependencies.

```sh
npm i @knuckleswtf/scribe-adonis
```

--------------------------------

### Check Installed Scribe Version

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/nodejs/95-troubleshooting.md

Use this command to determine the currently installed version of Scribe. This is useful for checking if an update is available or needed.

```bash
npm list @knuckleswtf/scribe
```

--------------------------------

### Omitting Optional Parameters in Examples

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/nodejs/documenting/40-url-parameters.md

To exclude an optional parameter from generated examples and response calls, append 'No-example' to its description. The parameter will still appear in the documentation.

```javascript
/**
 * @urlParam {integer} id required The ID of the post.
 * @urlParam {string} lang The language. No-example
 */
```

--------------------------------

### Header Attribute Example

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/reference/20-annotations.md

Describes a request header using the #[Header] attribute. The first argument is the header name, and the optional second argument is an example value.

```php
#[Header("X-Api-Version")]
#[Header("Content-Type", "application/xml")]
public function endpoint() {...}
```

--------------------------------

### Query Parameter Annotations

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/nodejs/reference/20-annotations.md

Use `@queryParam` to define query parameters. Specify type, name, requirement, description, and an optional example. Append 'No-example' to omit from examples.

```text
@queryParam {int} page
```

```text
@queryParam {int} page The page number.
```

```text
@queryParam {int} page required The page number. Example: 4
```

```text
@queryParam {int} page The page number. No-example
```

--------------------------------

### Initialize Scribe Configuration

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/nodejs/getting-started/2-express.md

Create the `.scribe.config.js` file by running the `scribe init` command. This command will prompt you for necessary information to set up your configuration.

```bash
npx scribe init
```

--------------------------------

### Configure Example Languages in Scribe

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/advanced/20-example-requests.mdx

Add new languages for example requests to your Scribe configuration file. You can specify a custom display name using an array key.

```php
'example_languages' => [
  'javascript',
  'ruby', // or 'Ruby 3' => 'ruby',
]
```

--------------------------------

### Define Example Responses with #[Response] Attribute

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/reference/20-annotations.md

Use the `#[Response]` attribute in PHP to define example responses. This attribute supports providing a JSON string, an array, a status code, and a description.

```php
#[Response('{"a": "b"}')]
#[Response(["a" => "b"])]
#[Response(["a" => "b"], 201)]
#[Response('{"a": "b"}', 201, "Operation successful")]
#[Response(["a" => "b"], description: "Success")]
public function endpoint() {...}
```

--------------------------------

### Response File Annotations

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/nodejs/reference/20-annotations.md

Use `@responseFile` to reference a file containing an example response. Specify an optional status code and scenario. The file path follows.

```text
@responseFile /an/absolute/path
```

```text
@responseFile 400 relative/path/from/your/project/root
```

```text
@responseFile status=400 scenario="Failed" relative/path/from/your/project/root
```

```text
@responseFile 400 scenario="Failed" relative/path/from/your/project/root
```

--------------------------------

### Specify Response File Path with #[ResponseFile] Attribute

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/reference/20-annotations.md

Use the `#[ResponseFile]` attribute to specify the path to a file containing an example response. This attribute accepts the file path, an optional status code, and an optional description.

```php
#[ResponseFile("/an/absolute/path")]
#[ResponseFile("relative/path/from/your/project/root", 400)]
#[ResponseFile("path/from/your/laravel/storage/directory", 400, description: "Failed")]
public function endpoint() {...}
```

--------------------------------

### Array and Object Parameters

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/nodejs/documenting/50-query-body-parameters.mdx

Demonstrates how to document array and object parameters for both query and body.

```APIDOC
## POST /api/process

### Description
This endpoint processes data with array and object parameters.

### Method
POST

### Endpoint
/api/process

### Parameters
#### Request Body
- **cars** (integer[]) - Optional - Array of car IDs. Example: [4, 6]
- **colors** (string[]) - Optional - Array of colors. Example: ["red", "blue"]
- **car_details** (object) - Optional - Car details. Example: {"name": "Carpenter", "year": 2019}
  - **car_details.name** (string) - Optional - Name of the car.
  - **car_details.year** (integer) - Optional - Year of the car. Example: 1997

### Request Example
```json
{
  "cars": [4, 6],
  "colors": ["red", "blue"],
  "car_details": {
    "name": "Carpenter",
    "year": 1997
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - Processing status.
```

--------------------------------

### Body Parameter Annotations

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/nodejs/reference/20-annotations.md

Use `@bodyParam` for request body parameters, including nested objects and arrays. Specify type, name, requirement, description, and an optional example. Append 'No-example' to omit from examples.

```text
@bodyParam {string} room_id
```

```text
@bodyParam {string} room_id required The room ID.
```

```text
@bodyParam {string} room_id The room ID. Example: r98639bgh3
```

```text
@bodyParam {string} room_id Example: r98639bgh3
```

```text
// Objects and arrays
```

```text
@bodyParam {object} user required The user data
```

```text
@bodyParam {string} user.name required The user's name.
```

```text
@bodyParam {int} user.age Example: 1000
```

```text
@bodyParam {object[]} people required List of people
```

```text
@bodyParam {string} people[].name Example: Deadpool
```

```text
// If your entire request body is an array
```

```text
@bodyParam {object[]} [] required List of things to do
```

```text
@bodyParam {string} [].name Name of the thing. Example: Cook
```

--------------------------------

### Subdomain Route Matching Example

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/reference/10-config.md

Demonstrates route matching when subdomain routing is configured. Only routes within the specified domain ('v2.acme.co') and matching the prefix ('api/*') are included.

```php
// 👍 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']);
```

--------------------------------

### Documenting File Uploads with @bodyParam

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/documenting/50-query-body-parameters.mdx

Use the `file` type with `@bodyParam` to document file inputs. This automatically sets the 'Content-Type' to 'multipart/form-data' for example requests. Provide an absolute or relative path to a file on your machine as an example.

```php
/**
 * @bodyParam caption string The image caption
 * @bodyParam image file required The image.
 */
```

--------------------------------

### Generate Multiple Docs Sets

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/tasks/10-generating.md

Use the `--config` flag to generate multiple independent sets of documentation by specifying different configuration files.

```sh
php artisan scribe:generate --config scribe_admin
```

--------------------------------

### Describe Body Parameters with Tags

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/reference/20-annotations.md

Use tags to describe request body parameters. Specify type, required status, description, and examples. Supports nested objects and arrays. Use 'Enum:' for allowed values and 'No-example' to exclude from examples.

```php
@bodyParam language string The language. Enum: en, de, fr
@bodyParam language string The language. Enum: en, de, fr. Example: en
@bodyParam room_id string
@bodyParam room_id string required The room ID.
@bodyParam room_id string The room ID. Example: r98639bgh3
@bodyParam room_id string Example: r98639bgh3

// Objects and arrays
@bodyParam user object required The user data
@bodyParam user.name string required The user's name.
@bodyParam user.age int Example: 1000
@bodyParam people object[] required List of people
@bodyParam people[].name string Example: Deadpool

// If your entire request body is an array
@bodyParam [] object[] required List of things to do
@bodyParam [].name string Name of the thing. Example: Cook
```

--------------------------------

### Documenting Body Parameters with Nested Objects and Arrays

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/nodejs/documenting/50-query-body-parameters.mdx

This example shows how to document a user object with nested properties and an array of car objects, including their respective fields.

```javascript
/**
* @bodyParam {object} user required The user details
* @bodyParam {string} user.name required The user's name
* @bodyParam {string} user.age required The user's age
* @bodyParam {int[]} friend_ids List of the user's friends.
* @bodyParam {object[]} cars List of cars
* @bodyParam {string} cars[].year The year the car was made. Example: 1997
* @bodyParam {string} cars[].make The make of the car. Example: Toyota
*/
```

--------------------------------

### Object Field Syntax Comparison

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/blog/2020-10-26-laravel-v2.md

Demonstrates the syntax for documenting an object with a string field, noting that this syntax remains unchanged.

```php
@bodyParam cars object
@bodyParam cars.name string
```

--------------------------------

### Documenting URL Parameters with @urlParam Tags

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/documenting/40-url-parameters.mdx

Use the @urlParam tag in PHPDoc blocks to describe URL parameters. You can specify the name, type, required status, and a description. For enums and examples, append 'Enum: <values>' and 'Example: <value>' to the description.

```php
/**
 * @urlParam id integer required The ID of the post.
 * @urlParam lang The language. Enum: en, fr Example: en
 */
public function getPost()
{
    // ...
}
```

```php
/**
 * @urlParam id required The ID of the post.
 * @urlParam lang The language. No-example
 */
```

--------------------------------

### Generate Docs for Express

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/nodejs/0-intro.mdx

Generate your API documentation for an Express application by specifying the path to your app file. Replace <your-app-file>.js with the actual path.

```bash
npx scribe generate -a <your-app-file>.js
```

--------------------------------

### POST /createPost (using Form Request)

Source: https://github.com/knuckleswtf/scribe-docs/blob/master/laravel/documenting/50-query-body-parameters.mdx

Demonstrates defining query and body parameters within a Form Request class.

```APIDOC
## POST /createPost

### Description
Creates a new post, with parameters defined in a Form Request.

### Method
POST

### Endpoint
/createPost

### Parameters
#### Query Parameters
- **lang** (string) - Required - The language.

#### Request Body
- **title** (string) - Optional - The title of the post.
- **body** (string) - Optional - The content of the post.

### Request Example
```json
{
  "title": "New Blog Post",
  "body": "This is the content for the new blog post."
}
```

### Response
#### Success Response (200)
- **id** (integer) - The ID of the newly created post.
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "id": 123,
  "message": "Post created successfully."
}
```
```