OpenAPI CLIの使用:カスタム前処理

Oops, now there is no way to see known values in the generated reference docs. The manual fix is to add these values to the description . But this is too cumbersome, especially if you’ll ever want to change presentation format.

Preprocessor for the rescue! What we want it to do:

1. Find all properties with x-aviskase-enum property.
2. Grab the list of values, format them nicely, and add it to the description . Make sure not to overwrite existing description if it’s already present!

Let’s create a preprocessor first ./plugins/preprocessors/add-enum-to-description.js :

//@ts-check
module.exports = AddEnumToDescription;

/** @type { import('@redocly/openapi-core/src/visitors').Oas3Preprocessor } */
function AddEnumToDescription(options) {
  const vendorExtension = options.vendorExtension || 'x-enum';
  return {
    Schema(schema) {
      if (schema[vendorExtension]) {
        schema.description = appendToDescription(schema[vendorExtension], schema.description);
      }
    },
  };
}

function appendToDescription(values, description) {
  let additionalDescription = `Possible values: ${values.map(v => `\`${v}\``).join(', ')}`;
  if (description) {
    return `${description}\n\n${additionalDescription}`;
  }
  return additionalDescription;
}

What’s happening here:

• We export a preprocessor function AddEnumToDescription that accepts configuration options :
  • vendorExtension option is used to define extension name for extensible enumeration. If not provided, it equals to x-enum .
• All openapi-cli preprocessors should return a visitor. In our case, we specifically indicate to take into account only schema nodes.
• If a schema has defined extensible enumeration property, we update its description with formatted list of values.

Note: Per documentation, for type support you can use import('@redocly/openapi-cli').Oas3Preprocessor} . It never worked for me, so I use a “full path” import('@redocly/openapi-core/src/visitors').Oas3Preprocessor .

Let’s keep our preprocessor (and the future ones) bundled inside one plugin via ./plugins/custom-preprocessors.js :

//@ts-check
const AddEnumToDescription = require('./preprocessors/add-enum-to-description');
const id = 'custom-preprocessors';

/** @type { import('@redocly/openapi-core/src/config/config').PreprocessorsConfig } */
const preprocessors = {
  oas3: {
    'add-x-enum-to-description': AddEnumToDescription,
  },
};

module.exports = {
  id,
  preprocessors,
};

Here we defined plugin’s id and a mapping between preprocessor’s name ( add-x-enum-to-description ) and its implementation.

Then we need to add this custom plugin to the .redocly.yaml and to enable the preprocessor:

...
lint:
  plugins:
    - './plugins/custom-preprocessors.js'
  preprocessors:
    custom-preprocessors/add-x-enum-to-description:
      vendorExtension: x-aviskase-enum
...

Now, when we render a reference documentation, we can see all values with simple markdown formatting.