タケユー・ウェブ日報

Webシステム受託会社の業務の中での気づきや調べごとのメモ。

Stoplight Studio を試す

OpenAPI の定義ファイルの作成と管理のためのツールを探していて、Stoplight Studio が良いと聞いたので試してみることにしました。

stoplight.io

f:id:uzuki05:20200509103856p:plain
Stoplight Studio

Stoplight Studio の触れ込み

Next gen editor for API design & technical docs (API設計と技術文書のための次世代エディタ)

Design APIs 10x faster with our free OpenAPI editor. Prototype and share your API within minutes.

無料の OpenAPI エディタを使用して、API を 10 倍速く設計します。数分以内にAPIをプロトタイプ化して共有します。

OpenAPI v2 & v3 API Designer (OpenAPI v2 & v3 APIデザイナー)

Start designing your API in minutes. Use the OpenAPI Specification (formerly known as Swagger) with Stoplight Studio to design consistent and standardized HTTP APIs for your organization. Without writing any code, model complex APIs faster than ever while simultaneously getting feedback on your prototypes with our instant mock servers.

数分でAPIの設計を開始します。Stoplight StudioでOpenAPI仕様(旧称Swagger)を使用して、一貫性のある標準化されたHTTP APIを設計します。コードを書くことなく、複雑なAPIをこれまで以上に迅速にモデル化すると同時に、インスタントモックサーバーを使用してプロトタイプのフィードバックを得ることができます。

A Powerful OpenAPI v2 & v3 Visual Editor (パワフルなOpenAPI v2 & v3ビジュアルエディタ)

Design an API with speed and efficiency from scratch. Stoplight Studio decreases the learning curve so you don’t need to be an OpenAPI expert to create first-class API designs. Describe endpoints, headers, bodies, multiple responses, query string parameters, shared models, and examples, and much more for complex APIs.

ゼロから迅速かつ効率的に API を設計します。Stoplight Studioは学習曲線を減らしてくれるので、OpenAPIの専門家でなくてもファーストクラスのAPIデザインを作成できます。エンドポイント、ヘッダ、ボディ、複数応答、クエリ文字列パラメータ、共有モデル、例など、複雑な API のための多くの機能を説明します。

Git Integration for Collaboration and Offline File Support (Git との統合によるコラボレーションとオフラインファイルのサポート)

Use the Git integration with your organization’s Git provider (GitHub, GitLab, Bitbucket, etc.). Invite teammates, partners, and API consumers to view and collaborate on your API designs privately or publicly with the tooling you already know and use.

With Offline File Support, open an existing OpenAPI document on your local machine or start from scratch with a new API, zero coding required. You can also share your OpenAPI document where ever you want.

組織のGitプロバイダー(GitHub、GitLab、Bitbucketなど)とのGit統合を使用します。チームメイト、パートナー、API消費者を招待して、APIデザインを非公開で、または既に知っていて使用しているツールを使って公開して、APIデザインを表示して共同作業を行うことができます。

オフラインファイルサポートでは、ローカルマシン上で既存のOpenAPIドキュメントを開くか、新しいAPIでゼロから始めることができ、コーディングは必要ありません。また、お好きな場所で OpenAPI ドキュメントを共有することもできます。

Instant Mock Servers (インスタントモックサーバー)

Instantly prototype and collaborate on your API design with our integrated, instant Mock Servers, powered by Prism. A mock API simulates the behavior of a real API allowing collaboration and feedback on your API design. Automatically update to match your API design. Mock a single API or multiple APIs at once.

Increase efficiency by allowing your frontend teams to start implementation while the backend team develops the API.

Prismを搭載した統合されたインスタントモックサーバーを使用して、API設計のプロトタイプを即座に作成し、共同作業を行うことができます。モックAPIは、実際のAPIの動作をシミュレートし、API設計のコラボレーションとフィードバックを可能にします。APIデザインに合わせて自動的に更新されます。1つのAPIまたは複数のAPIを一度にモックします。

バックエンドチームがAPIを開発している間にフロントエンドチームが実装を開始できるようにすることで、効率を向上させます。

Prism

stoplight.io

Prism, an Open-Source HTTP Mock & Proxy Server

Accelerate API development with realistic mock servers, powered by OpenAPI documents.

オープンソースのHTTPモック&プロキシサーバPrism

OpenAPIドキュメントを利用したリアルなモックサーバーでAPI開発を加速します。

Generate API Documentation with OpenAPI and Markdown (OpenAPIとMarkdownAPIドキュメントを生成する)

Create API documentation in minutes. Combine OpenAPI documents with Markdown to create robust, searchable, internal and external API documentation for your organization.

数分でAPIドキュメントを作成します。OpenAPIドキュメントとMarkdownを組み合わせて、組織のための堅牢で検索可能な内部および外部APIドキュメントを作成します。

OpenAPI Linting and API Style Guides (OpenAPIリンティングとAPIスタイルガイド)

Ask 100 API designers what makes a good API design and you’ll get 101 answers, but all most developers really want is consistency. Using an API style guide, can reduce decision making and improve consistency for all your teams.

With built-in linting and API style guides, powered by Spectral, Stoplight Studio can improve the quality of your API. You can use the default style guide, extend it, or write one to match your organization’s style guide (coming soon in Studio).

100人のAPIデザイナーに何が良いAPIデザインになるのかを聞いてみると、101の答えが返ってきます。APIスタイルガイドを使用することで、意思決定を減らし、すべてのチームの一貫性を向上させることができます。

Spectralが提供する組み込みのリンティングとAPIスタイルガイドにより、Stoplight StudioはAPIの品質を向上させることができます。デフォルトのスタイルガイドを使用することも、拡張することも、組織のスタイルガイドに合わせて記述することもできます(Studioでは近日公開予定)。

Spectral

stoplight.io

Spectral, an Open Source JSON/YAML Linter

Improve the quality of your API descriptions, Kubernetes config, GitHub Actions, or any other JSON/YAML data.

Spectral, オープンソースJSON/YAML リンター

API の説明、Kubernetes の設定、GitHub のアクション、その他の JSON/YAML データの品質を向上させます。

インストール

Web版、Macアプリ、Windowsアプリ、Linuxアプリ が提供されています。

私は Windows 使いなので、Windowsアプリ版をダウンロード・インストールします。

f:id:uzuki05:20200509111457p:plain

Getting Started

ドキュメントのGetting Startedに従って進めてみます。

stoplight.io

最初のプロジェクトを作成する

Open Git Project に提供されているサンプルプロジェクトのGitHubリポジトリURL https://github.com/stoplightio/studio-demo を指定して、プロジェクトを作成します。

f:id:uzuki05:20200509112102p:plain

f:id:uzuki05:20200509112406p:plain
プロジェクト作成完了時の画面

API記述ドキュメントの作成

f:id:uzuki05:20200509112724p:plain
新しいAPIの作成

API作成モーダルが開くので、

  • API
  • 仕様

を入力して Create をクリック。

f:id:uzuki05:20200509112822p:plain
API作成ダイアログ

API記述ドキュメントを作成できました。

f:id:uzuki05:20200509113041p:plain
作成されたAPI記述ドキュメント

エンドポイントの作成

エンドポイントは、個別のパスと操作です。

f:id:uzuki05:20200509115507p:plain
新しいエンドポイントの作成

エンドポイント作成モーダルが開くので、

  • エンドポイントを作成したいAPI記述ドキュメント
  • 管理用のタグ
  • Path
  • 存在する操作とその説明

を入力して Create をクリック。

f:id:uzuki05:20200509120009p:plain
エンドポイント作成モーダル

エンドポイントを作成できました。

f:id:uzuki05:20200509120414p:plain
作成されたエンドポイント

モデルの作成

モデルではAPIで使用されるデータ構造を定義できます。

stoplight.io

f:id:uzuki05:20200509135331p:plain
新しいモデルの作成

モデル作成モーダルが開くので

  • モデル名
  • タグ
  • スコープ

を入力して Create をクリック。

f:id:uzuki05:20200509135612p:plain
モデル作成モーダル

モデルを作成できました。

f:id:uzuki05:20200509135738p:plain
作成されたモデル

スキーマ定義

わかりやすいGUIスキーマエディタが使えます。

f:id:uzuki05:20200509144850p:plain
スキーマエディター

フォーマットやEnumなど追加のプロパティも設定できます。

f:id:uzuki05:20200509145105p:plain
追加のプロパティ

stoplight.io

モデルをエンドポイントの応答に使う

GET /addresses の 200 応答として Address モデルの配列を返す定義を作ってみます。

応答の Schema で

  • Type: `array``
  • Subtype: $ref
  • $ref target: #/definitions/Address

を選びます。

f:id:uzuki05:20200509150121p:plain
エンドポイントの応答にモデルを指定する

モックサーバーを使ってみる

f:id:uzuki05:20200509150738p:plain
モックURLを確認する

応答は定義内容から自動生成してくれてますね。

f:id:uzuki05:20200509151231p:plain
モックサーバーの応答

Linter を使ってみる

右下にLinting結果が表示されています。

f:id:uzuki05:20200509151610p:plain
警告あり

クリックすると警告内容が表示されました。

f:id:uzuki05:20200509151702p:plain
警告一覧

クリックすると該当箇所にジャンプします。 今回はレスポンスを1つも定義していない操作があることについての警告なので、該当する操作が表示されました。

f:id:uzuki05:20200509151905g:plain
警告から該当ファイルに移動

この画面でレスポンスを定義すると警告が消えました。

f:id:uzuki05:20200509152716g:plain
警告が消えた

まとめ

VScodeの拡張でもOpenAPI記述ドキュメント用のフォームを表示できるものはあるが、やはり専用の統合開発環境だけあって、使い勝手がよいように感じました。

GUIで指示に従って操作するだけで形になるので、仕様に詳しい人がいないチームで「なんもわからん」という状態でも始めやすいかなと思いました。

しばらく使ってみて、各機能の使い方などまたまとめていきたいと思います。