@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
- The guide below assumes you already have redocly installed.
Install the plugin as a project dependency using:
yarn add --dev @masabi/redocly-plugin
- 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
- 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
- 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.
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