VSCodeのRedocly OpenAPIプラグインの使い方
モジュールインストールと拡張機能インストール
redoc-cliが非推奨になったので、@redocly/cliを使用します。
$ npm init -y $ npm i @redocly/cli@latest
Redocly-OpenAPIプラグインを使用してプレビューや静的解析などができます。プレビューする場合はRedocly starterアカウントの設定が必要になりますが、静的解析だけならアカウント不要です。
プラグインインストールするとopen apiのyamlファイルを開くとredocly.yamlを作成するか聞かれるのでyesを押します。
プロジェクトルート直下にredocly.yamlが作成されます。redocly.yamlはlintの設定を記述することができるファイルになります。（その他も設定できます）
ruleを記述する
redocly.yamlにルールを記述することができます。
rules:
rule/operation-description:
subject:
type: Operation
property: description
assertions:
defined: true
minLength: 20
descriptionが20文字未満の場合エラーになります。
その他にも色々設定ができます。
HTML出力する
open apiのyamlファイルからhtmlを出力します。-oオプションを指定しなければデフォルトではredoc-static.htmlが出力されます。
$ npx redocly build-docs swagger.yaml -o index.html
index.htmlが出力されます。
redocly.yamlでDOWNLOADボタンを非表示にする
redocly.yamlに以下設定をします。
theme:
openapi:
hideDownloadButton: true
これでhtml出力するとDOWNLOADボタンが表示されなくなります。
tagsに日本語を入れると動作しない
tagsのnameに日本語を入れると生成されるhtmlでは日本語がomitされてしまいます。
tags:
- name: 削除API
description: 説明です。
- name: 登録API
description: 説明です。
このようにnameに日本語を入れるとomitされるので、どちらも「API」となってしまいます。
そのため、nameでは日本語を使用せずにhref用のnameを指定し、x-displayNameで表示したい名前を使用します。
tags:
- name: deleteAPI
description: 説明です。
x-displayName: 削除API
- name: registerAPI
description: 説明です。
x-displayName: 登録API
これでhtmlでは、「削除API」「登録API」と表示され、hrefはdeleteAPIやregisterAPIとなるので正常にリンクが動作するようになります。
参考サイト
KHI入社して退社。今はCONFRAGEで正社員です。関西で140-170/80～120万から受け付けております^^
得意技はJS(ES6),Java,AWSの大体のリソースです
コメントはやさしくお願いいたします^^
座右の銘は、「狭き門より入れ」「願わくは、我に七難八苦を与えたまえ」です^^
コメント