@masabi/redocly-plugin v0.0.7

@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

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.

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