はじめに
以前 "swagger specどうやって管理する問題" で、VSCodeを使ってswagger 2.0のjsonドキュメントをIntellisense込みで書く方法を記事にしました。
その中で使っているSwagger ViewerというVSCodeのExtensionのバージョン1.6で不具合があるらしく、jsonで書いたドキュメントがプレビューできなくなってしまいました。
そこで、yamlでIntellisense効かせながらswagger 2.0 (欲を言えばOpenAPI 3.0)のドキュメントを書きたいなぁ...と思ったので、やってみました。
たぶん他にもやり方はありそうなので、知ってる方はコメントとかで教えて頂きたいなぁ…とか思ってます。
手順
1. まずはVSCodeに必要なExtensionを入れます。
これだけです。
2. ちょっと設定する
VSCodeのsettings.json
にさっきのExtensionの設定を書きます。
"yaml.schemas": {
"http://json.schemastore.org/swagger-2.0": ["*swagger.yaml", "*swagger.yml"],
},
キーのhttp://json.schemastore.org/swagger-2.0
というのは、swagger 2.0のjson schemaが公開されているURLです。
値の["*swagger.yaml", "*swagger.yml"]
というのは、swagger 2.0のIntellisenseを効かせたいファイルの名前をglobで指定しています。
この設定の仕方からすると、json schemaが公開されているものに関してはなんでもIntellisenseを効かせられそうですね。
また、kedge(って何ですか?)とk8sについてはデフォルトでschemaを持ってるらしいので、以下のような設定もできるそうです。
(READMEより)
"yaml.schemas": {
"Kubernates": "/myYamlFile.yml",
"kedge": "/myKedgeApp.yaml"
},
できた!
これだけでIntellisenseが効くようになりました。(OpenAPI 3.0はjson schemaがまだ公開されてなくて断念…。)
思ったより簡単でした。
2019/3/26 追記
コメントより
価値のある記事をありがとうございます。
すでにご存知かもしれませんが、OpenAPI 3.0のjsonschemaも公開されていたみたいなので、この記事に辿り着いた方々のためにも共有させていただきます!
https://raw.githubusercontent.com/kogosoftwarellc/open-api/master/packages/openapi-schema-validator/resources/openapi-3.0.json
との情報を頂きました。 @toriiico さんありがとうございます。
手順2のところでsettings.jsonを以下のようにすると、OpenAPI 3.0のIntellisenseが効くようになります。
"yaml.schemas": {
"https://raw.githubusercontent.com/kogosoftwarellc/open-api/master/packages/openapi-schema-validator/resources/openapi-3.0.json": ["*swagger.yaml", "*swagger.yml"],
},