メインコンテンツへスキップ
見出し画像

OpenAPI(Swagger)とPrismを利用してAPIモックを立ててみる!

    こんにちは!
    「APIの開発って、フロントエンドとバックエンドの連携が大変...」
    「バックエンドができるまでフロントエンドの開発が進められない...」
    「テスト用のダミーデータを手動で作るのがめんどくさい...」
    こんな悩み、ありませんか? 私も最近まで同じ悩みを抱えていました。そんな時に出会ったのがSwagger(OpenAPI)とPrismを使ったモックサーバーでした。

    簡単に言うとAPI仕様書を書くだけでサーバーがなくてもリクエストとレスポンスを返してくれる魔法のようなツールです✨
    「でも設定が難しそう...」と思うかもしれませんが、実は30分もあれば動かせます!!この記事では、私が実際につまづいたポイントも含めて、手順を丁寧に解説していきます!

    2.知っておきたい重要ワード

    OpenAPI仕様とは?

    一言で言うと: グローバルに利用されているAPI設計図

    • 🏗️ 家を建てる前に設計図を描くように

    • 📝 APIを作る前に仕様を決める

    • 🌍 世界中の開発者が使ってる標準フォーマット

    Prismとは?

    一言で言うと: 設計図から自動でモックサーバーを作るツール

    • ⚡ 上述のOpenAPI1つでサーバーが立つ

    • 🎭 想定のAPIの振る舞いをしてくれる

    • 🔧 ローカルでセットアップが簡単

    環境構築

    ※あらかじめNode.jsをインストールしておいてください

    作業用フォルダの準備

    mkdir openapi-prism-tutorial
    cd openapi-prism-tutorial

    お使いのIDEでこのフォルダを開いてください。
    本稿ではVSCodeを利用します。

    VS Codeの拡張機能追加

    VS Codeで以下の拡張機能をインストールしてください

    1. YAML (Red Hat製)→インデントエラーに気づかせてくれる

    2. OpenAPI (Swagger) Editor (42Crunch製)→OpenAPI仕様書の構文チェック

    画像
    画像

    Prismのインストール

    npm install -g @stoplight/prism-cli

    Prismが正しくインストールされたか確認

    prism --version
    画像
    現時点の最新版がインストールされました✨ これで準備完了です!

    3.実践

    step1:OpenAPIを作成してみる

    それでは実際に手を動かしていきましょう!
    まずはAPI仕様書(OpenAPI)を作成します。

    VS Codeで先ほど作成したopenapi-prism-tutorialディレクトリの配下に新しいファイルtodo-api.yamlを作成してyamlファイルに記述していきます。

    以下をコピー&ペーストしてください

    openapi: 3.0.3
    info:
      title: TODO API
      description: シンプルなTODO管理API
      version: 1.0.0
    
    servers:
      - url: http://localhost:4010
        description: モックサーバー
    
    paths:
      /todos:
        get:
          summary: TODO一覧を取得
          description: すべてのTODOアイテムを取得します
          responses:
            '200':
              description: 成功
              content:
                application/json:
                  schema:
                    type: array
                    items:
                      $ref: '#/components/schemas/Todo'
                  example:
                    - id: 1
                      title: "牛乳を買う"
                      completed: false
                    - id: 2
                      title: "プレゼン資料作成"
                      completed: true
    
        post:
          summary: 新しいTODOを作成
          description: 新しいTODOアイテムを作成します
          requestBody:
            required: true
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/NewTodo'
                example:
                  title: "買い物に行く"
          responses:
            '201':
              description: 作成成功
              content:
                application/json:
                  schema:
                    $ref: '#/components/schemas/Todo'
    
    components:
      schemas:
        Todo:
          type: object
          properties:
            id:
              type: integer
              description: TODO ID
              example: 1
            title:
              type: string
              description: TODOのタイトル
              example: "牛乳を買う"
            completed:
              type: boolean
              description: 完了フラグ
              example: false
          required:
            - id
            - title
            - completed
    
        NewTodo:
          type: object
          properties:
            title:
              type: string
              description: TODOのタイトル
              example: "買い物に行く"
          required:
            - title

    step2:Prismによってモックを立てる


    ターミナルで以下のコマンドを実行してください

    prism mock todo-api.yaml
    画像
    こんな感じの表示が出るはずです!
    もうモックサーバーは立ち上がっています!

    Step3:OpenAPIページ(Swagger UI)から実行してみる

    いよいよ作成したモックAPIを叩きます!まずはSwagger UIを使ってみましょう! Swagger UIは、APIテスト用の標準的なWebインターフェースです。

    VS Codeで以下の拡張機能をインストールしてください

    画像

    Viewerを開くには以下のどちらかを実行
    ・Shift+Alt+p
    ・コマンドパレットからPreview Swaggerを選択
    先ほどのtodo-api.yamlを開くと画像右側のように綺麗にUIが表示されます。

    画像
    このようにUIが開きます

    それではGET /todosを実際に実行してみましょう

    手順

    1. GET /todos(青いボックス)をクリック

    2. 「Try it out」ボタンを探してクリック

    3. 「Execute」ボタンをクリック

    期待される結果

    • Response codeが200

    • Response bodyに牛乳を買う、プレゼン資料作成のTODOが返ってくる

    画像
    画像

    OpenAPI仕様書で定義したサンプルのデータが、そのまま返ってきました!
    下記のポイントを押さえてください

    • OpenAPI仕様書に書いたサンプルのデータである

    • PrismがAPIのモックとして機能してくれた

    • Swagger UIで実際のAPIのようにテストできた

    Step4: Postmanから上記のモックを実行してみる

    今度はAPIのテストをする際によく使われるPostmanからも同じモックサーバーをテストしてみましょう!

    1. Postmanをインストールしてくださいローカルホストはブラウザ版ではアクセスできなかったので注意ください(https://www.postman.com/jp/downloads/)

    2. Postmanを開く

    3. 新しいリクエストを作成

    4. MethodをGETに設定

    5. URLにhttp://127.0.0.1:4010/todosを入力

    6. Sendボタンをクリック

    画像

    Prismで建てたモックAPIにリクエストして、レスポンスを受け取ることができました!

    まとめ

    OpenAPIとPrismを使ったAPIモック作成、いかがでしたか? 今回作成したものを振り返ると 

    1. OpenAPI仕様書でAPI設計ができる

    2. Prismで瞬時にモックサーバーが立てられる

    3. Swagger UIでAPI仕様書が見れる

    4. Postmanでも本格的なAPIテストができる

    最初は「また新しいツールか...覚えること多すぎ」って思ってましたが実際に使ってみるととても便利ですね!API開発のフロントエンドとバックエンドの連携も容易になりそうです!

    さいごまで読んでいただき、ありがとうございました!

    企画意図

    弊社ではエンジニア教育と、未経験者の副業登用に力を入れております。本記事も副業でのナレッジを生徒に記事に落としていただきました。今後エンジニアを目指している方、開発でお困りの企業様、気兼ねなくお声がけください!

    あなたへのおすすめ