Open4
redocly decoratorsを調査
OSAMU NAKAMURARedocly CLI のプラグインにdecorator という仕組みがある。
decoratorを利用するとOpenAPI の要素を書き換えられる。
OSAMU NAKAMURAdecorator は プラグインの位置機能として実装する。
- カスタムプラグインの仕組みの公式説明はここ
- decorator の公式説明
decorator はVisitorパターンで実装する。
Node Typeはここに一覧がある。
公式ドキュメントの Custom decoratorsの例として、 descriptionに絵文字を追加するコードが挙げられている。
この例では、 Operation ノードタイプに対して処理を追加している。
module.exports = OperationSparkle;
function OperationSparkle() {
console.log("adding sparkles ... ");
return {
Operation: {
leave(target) {
if(target.description) {
target.description = "✨ " + String(target.description);
}
}
},
}
};
decorator の開発はだいたい以下の流れ：
redocly.yaml の plugins フィールドにプラグインソースのパスを指定する。
plugins:
- plugins/sparkle.js
decorators:
sparkle/operation-sparkle: on
plugins に指定したパスのJSソースでプラグイン情報を返す関数を実装する。
// Decorator の実装。
const OperationSparkle = require("./decorators/operation-sparkle.js")
module.exports = function sparklePlugin() {
return {
id: "sparkle", // redocly.yalm の decorators: sparkle/... と一致させる
decorators: {
oas3: {
"operation-sparkle": OperationSparkle, // redocly.yalm の decorators: sparkle/operation-sparkle と一致させる
}
}
}
}
plugins/decorators/operation-sparkle.js は以下の通り（再掲）
module.exports = OperationSparkle;
function OperationSparkle() {
console.log("adding sparkles ... ");
return {
Operation: {
leave(target) {
if(target.description) {
target.description = "✨ " + String(target.description);
}
}
},
}
};
Visitor は enter, leave, skip をそれぞれ実装できる
第一引数は node, 第二引数が コンテキスト。第四引数がよくわからない。
skip のみ、真偽値を返せる。true を返すと omit するっぽい。
ctx は、location などノードに関する情報が格納されるので、ctx.location.pointer でrefがとれる