LoginSignup
30
27

More than 5 years have passed since last update.

VSCodeでswagger 2.0のyamlドキュメントを快適に書きたい

Last updated at Posted at 2018-03-27

はじめに

以前 "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の設定を書きます。

settings.json
    "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より)

settings.json
    "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が効くようになります。

settings.json
 "yaml.schemas": {
 "https://raw.githubusercontent.com/kogosoftwarellc/open-api/master/packages/openapi-schema-validator/resources/openapi-3.0.json": ["*swagger.yaml", "*swagger.yml"],
 },
30
27
2

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
30
27