npm package: @masabi/redocly-plugin
Description: A [custom plugin for Redocly](https://redocly.com/docs/cli/custom-plugins/) designed to make building OpenAPI specifications easier at scale.
Author: Rob Morgan
Latest version: 0.0.90

# @masabi/redocly-plugin

## About

A [custom plugin for Redocly](https://redocly.com/docs/cli/custom-plugins/) designed to make building OpenAPI specifications easier at scale.

## Installation & Usage

1. The guide below assumes you already have redocly installed.

Install the plugin as a project dependency using:
```bash
yarn add --dev @masabi/redocly-plugin
```

2. Include a reference to the plugin within your `.redocly.yaml` configuration file.

_NB: Redocly doesn't resolve node modules by name automatically, so you have to reference the module using a relative path_

3. Enable & configure the decorators that you want to use from the plugin within your `.redocly.yaml` configuration file.

**Example `.redocly.yaml`**
```yaml
plugins:
  - './node_modules/@masabi/redocly-plugin'
decorators:
  masabi/verbose-parameter-naming: on
  masabi/global-request-parameters:
    useVerboseParameterNaming: true
```

4. Run redocly as normal.

## Decorators in this Plugin

### Global Request Parameters (`masabi/global-request-parameters`)

#### Configuration Options

| Option Name | Type | Default Value | Description |
| --- | --- | --- | --- |
| `useVerboseParameterNaming` | `boolean` | `false` | Set to `true` when using this decorator in conjunction with the [Verbose Parameter Naming decorator](#verbose-parameter-naming) which is included with this plugin to ensure consistent naming throughout the specification |

#### Description

This decorator takes the parameters referenced under the top-level `x-global-request-parameters` key and adds them to every request in the specification.

If the parameter is already defined locally within the request then it will not be overridden by this decorator.

_NB: The `x-global-request-parameters` object is removed from the output specification during the bundling process._

#### Example
**Before**
```yaml
x-global-request-parameters:
  - $ref: './parameters/path/RegionId.yaml'

paths:
  /{regionId}/demo/
    post:
      operationId: demonstration
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: string
                example: 'OK'
```

**After**
```yaml
paths:
  /{regionId}/demo:
    post:
      operationId: demonstration
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: string
                example: OK
    parameters:
      - $ref: '#/components/parameters/RegionId'
components:
  parameters:
    RegionId:
      in: path
      name: regionId
      schema:
        type: string
      required: true
```

### Global Response Headers (`masabi/global-response-headers`)

#### Configuration Options

None

#### Description

This decorator takes the headers referenced under the top-level `x-global-response-headers` key and adds them to every response in the specification.

If the header is already defined locally within the request then it will not be overridden by this decorator.

_NB: The `x-global-response-headers` object is removed from the output specification during the bundling process._

#### Example

**Before**
```yaml

x-global-response-headers:
  Example:
    schema:
      $ref: './schemas/Example.yaml'

paths:
  /demo
    post:
      operationId: demonstration
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: string
                example: 'OK'
```

**After**
```yaml
  /demo:
    post:
      operationId: demonstration
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: string
                example: OK
          headers:
            Example:
              schema:
                $ref: '#/components/schemas/Example'
```

### Global Tag Inclusion (`masabi/global-tag-inclusion`)

#### Configuration Options

None

#### Description

Ensures all tags assigned to Operations that encountered during the bundling process are included in the top-level `tags` collection for the API specification to ensure consistent navigation within the HTML documentation.

### Translated Fields (`masabi/translated-fields`)

#### Configuration Options

| Option Name | Type | Default Value | Description |
| --- | --- | --- | --- |
| `formatLabel` | `string` | `translated` | Label used to wrap the `format` of fields identified with the `x-translated` extension |
| `descriptionSuffix` | `string` | _undefined_ | When defined, this text will be appended to the `description` of fields identified with the `x-translated` extension. <br> If a field does not have a `description` defined for it, then the `descriptionSuffix` will be used as the `description`. |

#### Description

This decorator modifies the documentation for Schema parameters identified with the extension `x-translated: true` to indicate that the value for that field will vary depending on the language context.

#### Example
**Before**
```yaml

paths:
	/{regionId}/demo/
		post:
			operationId: demonstration
			responses:
				'200':
					description: Success
					content:
						application/json:
							schema:
								type: string
								example: 'OK'
								x-translated: true
```

**After**
```yaml
paths:
	/{regionId}/demo:
		post:
			operationId: demonstration
			responses:
				'200':
					description: Success
					content:
						application/json:
							schema:
								type: string
								description: The value of this field is translated based the request context 
								example: OK
								format: translated<string>
								x-translated: true
```

### Verbose Parameter Naming (`masabi/verbose-parameter-naming`)

#### Configuration Options

None

#### Description

This decorator incorporates the location (aka the value of its `in` field) of a parameter into its naming key that is generated during the bundling process.

By default, Redocly names their parameters in a way that can cause confusing naming, if a schema is used in more than one location (path/query/header), as it uses a naming approach based only on the file name of the parameter. However in OAS a parameter is a unique combination of name + location (defined though the `in` property).

_NB: The Redocly naming process tries to work around this by suffixing a number to the schema name if it encounters a conflict, which isn't pretty or descriptive as to the difference between the two  This extension aims to provide a clearer solution to the most common use case that results in a naming conflict arising in the first place._

#### Example

The following parameter object gets named `RegionIdPathParameter` saved under `#/components/parameters/RegionIdPathParameter`
```yaml
in: path
name: regionId
schema:
  type: string
required: true
```