@masabi/redocly-plugin

About

A custom plugin for Redocly 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:

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

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 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

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

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

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

  /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. 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

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

After

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

in: path
name: regionId
schema:
  type: string
required: true