API 管理ツール Stoplight を使ってみた

こんにちは、クラウドエースの遠矢です。
今回は、API 管理ツールの Stoplight を触る機会があったので使い方などを紹介します！

概要

• Stoplight とは何か？
  Stoplight とは包括的な API 開発プラットフォームで、API デザイン、文書化、テスト、公開などの機能が含まれます。

• コスト表

プラン	年間請求	月刊請求	ユーザ数	最大 プロジェクト数	特徴
free	なし	なし	1	1	基本的な API 設計とモック機能
Basic	$39	$49	3	無制限	小規模チーム向けの API 設計と ドキュメント作成
Startup	$99	$129	8	無制限	スタートアップ向けのユーザと プロジェクト対応
Pro Team	$319	$399	15	無制限	中規模チーム向けの API 設計 とチーム協力機能
Enterprise	カスタム	カスタム	カスタム	無制限	大規模企業向けのカスタマイズ とサポート

※ユーザを規定以上追加すると人数に応じてさらに課金

• Basic と Startup は $9、Pro Team は $19 になります。
• 詳しくは以下のリンクをご覧ください

Stoplight の主要機能(メリット)

• GUI で API 仕様書を作成可能
  OpenAPI の仕様書を YAML ファイル を編集せずに GUI を使用して直感的に作成できます。

• モックサーバー機能
  モックサーバーの機能があり、開発とテストのために仮想 API サーバーを素早く構築できます。また、OpenAPI 仕様に基づいて API を自動生成し、様々な HTTP ステータスコードとレスポンスを模擬することで、API のテストとデバッグを効率的に行うことができます。

• 共通スタイルガイド
  スタイルガイドという、API デザインの一貫性を確保するためのルール集を作成することができ、チームで共有して API を作成できます

共有スタイルガイド機能を利用するには、有料の Pro Team プラン以上への加入が必要です。

Stoplight の使い方

クラウド版とデスクトップ版

Stoplight はクラウド版とデスクトップ版の 2 種類あります。

• クラウド版の使用方法（アカウント作成方法）
  クラウド版はアカウントを作成すれば使用できます。

• 無料版の使用方法

1. 上の URL をクリック後、画面下の Stoplight for free をクリック
2. メールアドレスを入力
3. 会社名とワークスペース名を入力
4. 登録したメールアドレスに送られた番号を入力
5. アカウント作成

デスクトップ版の使用方法

1. 上の GitHub から自分の環境に合ったものをインストール
2. 作成したアカウントとワークスペース名を入力

アカウントを作成していない場合はクラウド版と同じように作成する必要があります。

メモ帳APIの作成

例として以下のメモ帳 API を Stoplight で定義してみます（デスクトップ版）

• この YAML 定義は、メモ帳 API の構造を示しています。paths セクションでは、GET /memos と POST /memos の 2 つのエンドポイントを定義しており、各エンドポイントのリクエストとレスポンスの形式が記述されています。

openapi: 3.0.0
info:
  title: メモ帳 API
  version: 1.0.0
servers:
  - url: http://api.memopad.com/v1
paths:
  /memos:
    get:
      summary: メモを全て取得
      responses:
        '200':
          description: メモのリストを返します
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Memo'
    post:
      summary: 新しいメモを作成
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Memo'
      responses:
        '201':
          description: 新しいメモが作成されました
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Memo'
components:
  schemas:
    Memo:
      type: object
      required:
        - content
      properties:
        id:
          type: string
          description: ユニークなID
        content:
          type: string
          description: メモの内容

1. Git リポジトリ連携

• 自分の GitHub アカウントと連携後作成したいリポジトリを clone して stoplight 作成画面に移動
  

2. New OpenAPI を選択し、v3.0 を選択

3. Form モードに切り替え、title とサーバーの URL を記入

4. components/schemas を定義するため Models ディレクトリで Memo スキーマを作成

• description（説明）は本のマークを選択すると入力できる
• required（必須項目）はビックリマークを選択することで必須項目であるかを設定できる
  

5. paths に /memos を作成し、GET と POST をそれぞれ定義

6. response には4.で作成した Memo スキーマを利用する

• Type で型を指定して、Components で Memoを指定する
  

7. ドキュメントの確認とモックサーバの使い方

• Preview で作成したドキュメントを見ることができる
  
• Try it でモックサーバの利用とクライアントコードの生成もできる
  

stoplight を使用する際の注意点（デメリット）

• 日本語対応はしていない
• アカウントが必須になり、定期的なログインが必要
• 無料プランだとクラウド版はプロジェクトが1つしか作成できない（デスクトップ版は Git リポジトリがあれば制限はない）

まとめ： Stoplight の体験と今後の展望

Stoplight を使ってみて、初心者や OpenAPI に不慣れな開発者にとって利用しやすいことが大きな魅力でした。

• 直感的な GUI
  Stoplight の直感的な GUI は、API 設計のプロセスを簡素化しました。コードベースのアプローチに慣れていないユーザーでも容易に API を設計し、試すことが可能です。
• 初学者への優しい環境
  OpenAPI の知識が浅い自分でも、API の基礎を学びながら効率的に作業を進めることができました。
• 運用の課題と考察
  ただし、実際の運用に移る際には、さまざまな要因を考慮する必要があります。特にコストやインフラの管理など、運用面での計画は慎重に行う必要があります。
• 今後の展望
  Stoplight の経験に基づき、次は日本語に対応している包括的な API 開発プラットフォーム「Apidog」にも触ってみたいと思います。
  Apidog についての詳細はこちら

Stoplight は多くの利点を提供する一方で、プロジェクトやチームの特定のニーズに合わせて適切なツールを選択することが重要です。
今後 OpenAPI ドキュメントの効率化を目指しているのならば Stoplight を使用してみてください。