OpenAPIのエディタはvscodeかSpotlight Studio

2022-09-06 2022-09-28 3分12秒

Contents

1 Stoplight Studio
- 1.1 openapi.yml の肥大化問題
- 1.2 VSCode プラグイン、Swagger Editor との比較
2 Stoplight Prism

Stoplight Studio

Stoplight Studio は Stoplight 社が開発する OSS の OpenAPI ドキュメント作成の GUI ツール。

openapi.yml の肥大化問題

openapi.yml の編集に普段は vscode とそのプラグイン openapi-designer を使っている。小さいドキュメントなら全く問題ない。

しかし、ドキュメントがデカくなると分割したくなるもので、パラメータやスキーマなどコンポーネントごとにディレクトリを掘りそれぞれ別の yml ファイルで分割管理するのだが、また変更対象のファイルを開くまで時間がかかり、どうしたもんかと悩む。

VSCode プラグイン、Swagger Editor との比較

Stoplight Studio を使うまで、VSCode の OpenAPI Designer という OpenAPI プレビューのプラグインを使いながら、VSCode コンポーネントをファイル分割して yaml で記述していたが、分割管理や、目的のコンポーネントへのジャンプ、分割ファイルの build など、いろいろ手間だった。

また Swagger Editor と競合するツールになるが、Swagger Editor は OpenAPI を素の yaml または json で記述するのに対し、Stoplight Studio は GUI でポチポチ設定が可能、また Swagger Editor と同じくコードで記述することも可能。

Stoplight Studio は SaaS 版とデスクトップ版があり自分はデスクトップ版を使っている。デスクトップ版は Stoplight 社のサイトからダウンロードできるが、email を入力しないといけない。Githubのリリースページからでもダウンロードできるのでこちらのほうがおすすめ。

Stoplight の GUI では、openapi の記述自体は 1 ファイルで完結しつつ、GUI で目的の Model スキーマや Response スキーマを辿れるので、Swagger Editor よりはるかに楽。

VSCode の OpenAPI Designer という OpenAPI プレビューのプラグインを使って、VSCode コンポーネントをファイル分割して記述

また openapi.yaml 自体がめちゃくちゃ長くなっても、いまのところ動作に影響することもないのでいい感じ。

Prism という API モックサーバツールも備わっているので、GUI からモックサーバを起動できる。Prism 自体は CLI ツールとしても提供されている。