<p>こんにちは、クラウドエースの遠矢です。<br>
今回は、API 管理ツールの Stoplight を触る機会があったので使い方などを紹介します！</p>
<h2 id="%E6%A6%82%E8%A6%81">
<a class="header-anchor-link" href="#%E6%A6%82%E8%A6%81" aria-hidden="true"></a> 概要</h2>
<ul>
<li>Stoplight とは何か？<br>
Stoplight とは包括的な API 開発プラットフォームで、API デザイン、文書化、テスト、公開などの機能が含まれます。</li>
</ul>
<span class="embed-block zenn-embedded zenn-embedded-card"><iframe id="zenn-embedded__47df4accd004" src="https://embed.zenn.studio/card#zenn-embedded__47df4accd004" data-content="https%3A%2F%2Fstoplight.io%2F" frameborder="0" scrolling="no" loading="lazy"></iframe></span>
<ul>
<li>コスト表</li>
</ul>
<table>
<thead>
<tr>
<th>プラン</th>
<th>年間請求</th>
<th>月刊請求</th>
<th>ユーザ数</th>
<th>最大 <br>プロジェクト数</th>
<th>特徴</th>
</tr>
</thead>
<tbody>
<tr>
<td>free</td>
<td>なし</td>
<td>なし</td>
<td>1</td>
<td>1</td>
<td>基本的な API 設計とモック機能</td>
</tr>
<tr>
<td>Basic</td>
<td>$39</td>
<td>$49</td>
<td>3</td>
<td>無制限</td>
<td>小規模チーム向けの API 設計と <br> ドキュメント作成</td>
</tr>
<tr>
<td>Startup</td>
<td>$99</td>
<td>$129</td>
<td>8</td>
<td>無制限</td>
<td>スタートアップ向けのユーザと <br> プロジェクト対応</td>
</tr>
<tr>
<td>Pro Team</td>
<td>$319</td>
<td>$399</td>
<td>15</td>
<td>無制限</td>
<td>中規模チーム向けの API 設計 <br> とチーム協力機能</td>
</tr>
<tr>
<td>Enterprise</td>
<td>カスタム</td>
<td>カスタム</td>
<td>カスタム</td>
<td>無制限</td>
<td>大規模企業向けのカスタマイズ <br> とサポート</td>
</tr>
</tbody>
</table>
<p>※ユーザを規定以上追加すると人数に応じてさらに課金</p>
<ul>
<li>Basic と Startup は $9、Pro Team は $19 になります。</li>
<li>詳しくは以下のリンクをご覧ください</li>
</ul>
<span class="embed-block zenn-embedded zenn-embedded-card"><iframe id="zenn-embedded__e092661256cc9" src="https://embed.zenn.studio/card#zenn-embedded__e092661256cc9" data-content="https%3A%2F%2Fstoplight.io%2Fcompare-all-plans" frameborder="0" scrolling="no" loading="lazy"></iframe></span>
<h2 id="stoplight-%E3%81%AE%E4%B8%BB%E8%A6%81%E6%A9%9F%E8%83%BD(%E3%83%A1%E3%83%AA%E3%83%83%E3%83%88)">
<a class="header-anchor-link" href="#stoplight-%E3%81%AE%E4%B8%BB%E8%A6%81%E6%A9%9F%E8%83%BD(%E3%83%A1%E3%83%AA%E3%83%83%E3%83%88)" aria-hidden="true"></a> Stoplight の主要機能(メリット)</h2>
<ul>
<li>
<p>GUI で API 仕様書を作成可能<br>
OpenAPI の仕様書を YAML ファイル を編集せずに GUI を使用して直感的に作成できます。</p>
</li>
<li>
<p>モックサーバー機能<br>
モックサーバーの機能があり、開発とテストのために仮想 API サーバーを素早く構築できます。また、OpenAPI 仕様に基づいて API を自動生成し、様々な HTTP ステータスコードとレスポンスを模擬することで、API のテストとデバッグを効率的に行うことができます。</p>
</li>
<li>
<p>共通スタイルガイド<br>
スタイルガイドという、API デザインの一貫性を確保するためのルール集を作成することができ、チームで共有して API を作成できます</p>
</li>
</ul>
<aside class="msg alert"><span class="msg-symbol">!</span><div class="msg-content">
<p>共有スタイルガイド機能を利用するには、有料の Pro Team プラン以上への加入が必要です。</p>
</div></aside>
<h2 id="stoplight-%E3%81%AE%E4%BD%BF%E3%81%84%E6%96%B9">
<a class="header-anchor-link" href="#stoplight-%E3%81%AE%E4%BD%BF%E3%81%84%E6%96%B9" aria-hidden="true"></a> Stoplight の使い方</h2>
<h3 id="%E3%82%AF%E3%83%A9%E3%82%A6%E3%83%89%E7%89%88%E3%81%A8%E3%83%87%E3%82%B9%E3%82%AF%E3%83%88%E3%83%83%E3%83%97%E7%89%88">
<a class="header-anchor-link" href="#%E3%82%AF%E3%83%A9%E3%82%A6%E3%83%89%E7%89%88%E3%81%A8%E3%83%87%E3%82%B9%E3%82%AF%E3%83%88%E3%83%83%E3%83%97%E7%89%88" aria-hidden="true"></a> クラウド版とデスクトップ版</h3>
<p>Stoplight はクラウド版とデスクトップ版の 2 種類あります。</p>
<ul>
<li>クラウド版の使用方法（アカウント作成方法）<br>
クラウド版はアカウントを作成すれば使用できます。</li>
</ul>
<span class="embed-block zenn-embedded zenn-embedded-card"><iframe id="zenn-embedded__43f547c970711" src="https://embed.zenn.studio/card#zenn-embedded__43f547c970711" data-content="https%3A%2F%2Fstoplight.io%2Fpricing" frameborder="0" scrolling="no" loading="lazy"></iframe></span>
<ul>
<li>無料版の使用方法</li>
</ul>
<ol>
<li>上の URL をクリック後、画面下の Stoplight for free をクリック</li>
<li>メールアドレスを入力</li>
<li>会社名とワークスペース名を入力</li>
<li>登録したメールアドレスに送られた番号を入力</li>
<li>アカウント作成</li>
</ol>
<details><summary>デスクトップ版の使用方法</summary><div class="details-content">
<span class="embed-block zenn-embedded zenn-embedded-card"><iframe id="zenn-embedded__8cae985f93d04" src="https://embed.zenn.studio/card#zenn-embedded__8cae985f93d04" data-content="https%3A%2F%2Fgithub.com%2Fstoplightio%2Fstudio%2Freleases" frameborder="0" scrolling="no" loading="lazy"></iframe></span>
<ol>
<li>上の GitHub から自分の環境に合ったものをインストール</li>
<li>作成したアカウントとワークスペース名を入力</li>
</ol>
<aside class="msg alert"><span class="msg-symbol">!</span><div class="msg-content">
<p>アカウントを作成していない場合はクラウド版と同じように作成する必要があります。</p>
</div></aside>
</div></details>
<h2 id="%E3%83%A1%E3%83%A2%E5%B8%B3api%E3%81%AE%E4%BD%9C%E6%88%90">
<a class="header-anchor-link" href="#%E3%83%A1%E3%83%A2%E5%B8%B3api%E3%81%AE%E4%BD%9C%E6%88%90" aria-hidden="true"></a> メモ帳APIの作成</h2>
<p>例として以下のメモ帳 API を Stoplight で定義してみます（デスクトップ版）</p>
<ul>
<li>この YAML 定義は、メモ帳 API の構造を示しています。paths セクションでは、GET /memos と POST /memos の 2 つのエンドポイントを定義しており、各エンドポイントのリクエストとレスポンスの形式が記述されています。</li>
</ul>
<div class="code-block-container"><pre><code>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: メモの内容
</code></pre></div><ol>
<li>
<h4 id="git-%E3%83%AA%E3%83%9D%E3%82%B8%E3%83%88%E3%83%AA%E9%80%A3%E6%90%BA">
<a class="header-anchor-link" href="#git-%E3%83%AA%E3%83%9D%E3%82%B8%E3%83%88%E3%83%AA%E9%80%A3%E6%90%BA" aria-hidden="true"></a> Git リポジトリ連携</h4>
</li>
</ol>
<ul>
<li>自分の GitHub アカウントと連携後作成したいリポジトリを clone して stoplight 作成画面に移動<br>
<img src="https://res.cloudinary.com/zenn/image/fetch/s--wLN2AwqR--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_1200/https://storage.googleapis.com/zenn-user-upload/deployed-images/eb77b66b36ca3fcca3df1af3.png%3Fsha%3D11a93bb9b70b5b64a61c56f12e3be3936fb5bb11" alt="Alt text" loading="lazy" class="md-img">
</li>
</ul>
<ol start="2">
<li>
<h4 id="new-openapi-%E3%82%92%E9%81%B8%E6%8A%9E%E3%81%97%E3%80%81v3.0-%E3%82%92%E9%81%B8%E6%8A%9E">
<a class="header-anchor-link" href="#new-openapi-%E3%82%92%E9%81%B8%E6%8A%9E%E3%81%97%E3%80%81v3.0-%E3%82%92%E9%81%B8%E6%8A%9E" aria-hidden="true"></a> New OpenAPI を選択し、v3.0 を選択</h4>
</li>
</ol>
<p><img src="https://res.cloudinary.com/zenn/image/fetch/s--U-CTUp1Y--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_1200/https://storage.googleapis.com/zenn-user-upload/deployed-images/c592f2ffb9d11a65cbfcd047.png%3Fsha%3Ddfc81147df74bae12e65fc4d13f7c4bccaf03fce" alt="Alt text" loading="lazy" class="md-img"></p>
<ol start="3">
<li>
<h4 id="form-%E3%83%A2%E3%83%BC%E3%83%89%E3%81%AB%E5%88%87%E3%82%8A%E6%9B%BF%E3%81%88%E3%80%81title-%E3%81%A8%E3%82%B5%E3%83%BC%E3%83%90%E3%83%BC%E3%81%AE-url-%E3%82%92%E8%A8%98%E5%85%A5">
<a class="header-anchor-link" href="#form-%E3%83%A2%E3%83%BC%E3%83%89%E3%81%AB%E5%88%87%E3%82%8A%E6%9B%BF%E3%81%88%E3%80%81title-%E3%81%A8%E3%82%B5%E3%83%BC%E3%83%90%E3%83%BC%E3%81%AE-url-%E3%82%92%E8%A8%98%E5%85%A5" aria-hidden="true"></a> Form モードに切り替え、title とサーバーの URL を記入</h4>
</li>
</ol>
<p><img src="https://res.cloudinary.com/zenn/image/fetch/s--78TglJeA--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_1200/https://storage.googleapis.com/zenn-user-upload/deployed-images/9fbaaf2495e967e6d4e66dc6.png%3Fsha%3D9f2f1a89e97ec15bb238b18ff20a1a2e5f052e4d" alt="Alt text" loading="lazy" class="md-img"></p>
<ol start="4">
<li>
<h4 id="components%2Fschemas-%E3%82%92%E5%AE%9A%E7%BE%A9%E3%81%99%E3%82%8B%E3%81%9F%E3%82%81-models-%E3%83%87%E3%82%A3%E3%83%AC%E3%82%AF%E3%83%88%E3%83%AA%E3%81%A7-memo-%E3%82%B9%E3%82%AD%E3%83%BC%E3%83%9E%E3%82%92%E4%BD%9C%E6%88%90">
<a class="header-anchor-link" href="#components%2Fschemas-%E3%82%92%E5%AE%9A%E7%BE%A9%E3%81%99%E3%82%8B%E3%81%9F%E3%82%81-models-%E3%83%87%E3%82%A3%E3%83%AC%E3%82%AF%E3%83%88%E3%83%AA%E3%81%A7-memo-%E3%82%B9%E3%82%AD%E3%83%BC%E3%83%9E%E3%82%92%E4%BD%9C%E6%88%90" aria-hidden="true"></a> components/schemas を定義するため Models ディレクトリで Memo スキーマを作成</h4>
</li>
</ol>
<ul>
<li>description（説明）は本のマークを選択すると入力できる</li>
<li>required（必須項目）はビックリマークを選択することで必須項目であるかを設定できる<br>
<img src="https://res.cloudinary.com/zenn/image/fetch/s--G7m-fvUY--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_1200/https://storage.googleapis.com/zenn-user-upload/deployed-images/14da8fde15641530070e6017.png%3Fsha%3Dfc6c7ad1c2bbb900ff9b0bd3c6dc39fe7565bb2a" alt="Alt text" loading="lazy" class="md-img">
</li>
</ul>
<ol start="5">
<li>
<h4 id="paths-%E3%81%AB-%2Fmemos-%E3%82%92%E4%BD%9C%E6%88%90%E3%81%97%E3%80%81get-%E3%81%A8-post-%E3%82%92%E3%81%9D%E3%82%8C%E3%81%9E%E3%82%8C%E5%AE%9A%E7%BE%A9">
<a class="header-anchor-link" href="#paths-%E3%81%AB-%2Fmemos-%E3%82%92%E4%BD%9C%E6%88%90%E3%81%97%E3%80%81get-%E3%81%A8-post-%E3%82%92%E3%81%9D%E3%82%8C%E3%81%9E%E3%82%8C%E5%AE%9A%E7%BE%A9" aria-hidden="true"></a> paths に /memos を作成し、GET と POST をそれぞれ定義</h4>
</li>
</ol>
<p><img src="https://res.cloudinary.com/zenn/image/fetch/s--ggsdfzEz--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_1200/https://storage.googleapis.com/zenn-user-upload/deployed-images/beba9d2f6f49047f87973db6.png%3Fsha%3D30b42ff8789b79fadb79105e25380bd4a62659aa" alt="Alt text" loading="lazy" class="md-img"></p>
<ol start="6">
<li>
<h4 id="response-%E3%81%AB%E3%81%AF4.%E3%81%A7%E4%BD%9C%E6%88%90%E3%81%97%E3%81%9F-memo-%E3%82%B9%E3%82%AD%E3%83%BC%E3%83%9E%E3%82%92%E5%88%A9%E7%94%A8%E3%81%99%E3%82%8B">
<a class="header-anchor-link" href="#response-%E3%81%AB%E3%81%AF4.%E3%81%A7%E4%BD%9C%E6%88%90%E3%81%97%E3%81%9F-memo-%E3%82%B9%E3%82%AD%E3%83%BC%E3%83%9E%E3%82%92%E5%88%A9%E7%94%A8%E3%81%99%E3%82%8B" aria-hidden="true"></a> response には4.で作成した Memo スキーマを利用する</h4>
</li>
</ol>
<ul>
<li>Type で型を指定して、Components で Memoを指定する<br>
<img src="https://res.cloudinary.com/zenn/image/fetch/s--mhnyNGNV--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_1200/https://storage.googleapis.com/zenn-user-upload/deployed-images/ee45296223f737d5a721f28a.png%3Fsha%3D3363a0bdbff73b4137b8e4e921ac17bb3473c0d2" alt="Alt text" loading="lazy" class="md-img">
</li>
</ul>
<ol start="7">
<li>
<h4 id="%E3%83%89%E3%82%AD%E3%83%A5%E3%83%A1%E3%83%B3%E3%83%88%E3%81%AE%E7%A2%BA%E8%AA%8D%E3%81%A8%E3%83%A2%E3%83%83%E3%82%AF%E3%82%B5%E3%83%BC%E3%83%90%E3%81%AE%E4%BD%BF%E3%81%84%E6%96%B9">
<a class="header-anchor-link" href="#%E3%83%89%E3%82%AD%E3%83%A5%E3%83%A1%E3%83%B3%E3%83%88%E3%81%AE%E7%A2%BA%E8%AA%8D%E3%81%A8%E3%83%A2%E3%83%83%E3%82%AF%E3%82%B5%E3%83%BC%E3%83%90%E3%81%AE%E4%BD%BF%E3%81%84%E6%96%B9" aria-hidden="true"></a> ドキュメントの確認とモックサーバの使い方</h4>
</li>
</ol>
<ul>
<li>Preview で作成したドキュメントを見ることができる<br>
<img src="https://res.cloudinary.com/zenn/image/fetch/s--tNJ8WlDH--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_1200/https://storage.googleapis.com/zenn-user-upload/deployed-images/06d5369e2f95b6816f509499.png%3Fsha%3De7942ed18c934272572c65c32151a42e7162954c" alt="Alt text" loading="lazy" class="md-img">
</li>
<li>Try it でモックサーバの利用とクライアントコードの生成もできる<br>
<img src="https://res.cloudinary.com/zenn/image/fetch/s--fzRFVHrc--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_1200/https://storage.googleapis.com/zenn-user-upload/deployed-images/d4a89dd13e8fc9e6665dcfaf.png%3Fsha%3D8bd2ca43900f3041fd98ec5462a07d74611325af" alt="Alt text" loading="lazy" class="md-img">
</li>
</ul>
<h2 id="stoplight-%E3%82%92%E4%BD%BF%E7%94%A8%E3%81%99%E3%82%8B%E9%9A%9B%E3%81%AE%E6%B3%A8%E6%84%8F%E7%82%B9%EF%BC%88%E3%83%87%E3%83%A1%E3%83%AA%E3%83%83%E3%83%88%EF%BC%89">
<a class="header-anchor-link" href="#stoplight-%E3%82%92%E4%BD%BF%E7%94%A8%E3%81%99%E3%82%8B%E9%9A%9B%E3%81%AE%E6%B3%A8%E6%84%8F%E7%82%B9%EF%BC%88%E3%83%87%E3%83%A1%E3%83%AA%E3%83%83%E3%83%88%EF%BC%89" aria-hidden="true"></a> stoplight を使用する際の注意点（デメリット）</h2>
<ul>
<li>日本語対応はしていない</li>
<li>アカウントが必須になり、定期的なログインが必要</li>
<li>無料プランだとクラウド版はプロジェクトが1つしか作成できない（デスクトップ版は Git リポジトリがあれば制限はない）</li>
</ul>
<h2 id="%E3%81%BE%E3%81%A8%E3%82%81%EF%BC%9A-stoplight-%E3%81%AE%E4%BD%93%E9%A8%93%E3%81%A8%E4%BB%8A%E5%BE%8C%E3%81%AE%E5%B1%95%E6%9C%9B">
<a class="header-anchor-link" href="#%E3%81%BE%E3%81%A8%E3%82%81%EF%BC%9A-stoplight-%E3%81%AE%E4%BD%93%E9%A8%93%E3%81%A8%E4%BB%8A%E5%BE%8C%E3%81%AE%E5%B1%95%E6%9C%9B" aria-hidden="true"></a> まとめ： Stoplight の体験と今後の展望</h2>
<p>Stoplight を使ってみて、初心者や OpenAPI に不慣れな開発者にとって利用しやすいことが大きな魅力でした。</p>
<ul>
<li>直感的な GUI<br>
Stoplight の直感的な GUI は、API 設計のプロセスを簡素化しました。コードベースのアプローチに慣れていないユーザーでも容易に API を設計し、試すことが可能です。</li>
<li>初学者への優しい環境<br>
OpenAPI の知識が浅い自分でも、API の基礎を学びながら効率的に作業を進めることができました。</li>
<li>運用の課題と考察<br>
ただし、実際の運用に移る際には、さまざまな要因を考慮する必要があります。特にコストやインフラの管理など、運用面での計画は慎重に行う必要があります。</li>
<li>今後の展望<br>
Stoplight の経験に基づき、次は日本語に対応している包括的な API 開発プラットフォーム「Apidog」にも触ってみたいと思います。<br>
Apidog についての詳細はこちら</li>
</ul>
<span class="embed-block zenn-embedded zenn-embedded-card"><iframe id="zenn-embedded__13673db8790b4" src="https://embed.zenn.studio/card#zenn-embedded__13673db8790b4" data-content="https%3A%2F%2Fapidog.com%2Fjp%2F" frameborder="0" scrolling="no" loading="lazy"></iframe></span>
<p>Stoplight は多くの利点を提供する一方で、プロジェクトやチームの特定のニーズに合わせて適切なツールを選択することが重要です。<br>
今後 OpenAPI ドキュメントの効率化を目指しているのならば Stoplight を使用してみてください。</p>


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

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

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

openapi

stoplight

Discussion