APIを用いたRESTful APIの設計

数週間前、OpenAPI仕様を使用してAPIの最初のAPIデザインについて話をする新しいポストシリーズを始めました.
あなたがまだこのシリーズの最初のポストを見なかったならば、私はあなたが読むのを止めて、クリックすることによってそれをチェックすることを勧めます.
今日のポストでは、OpenAPIドキュメントを使用して開発者の経験を改善し、並列処理を行うために、モックサーバを構築する方法について説明します.

😎 — 模擬概念

OpenAPIドキュメントを使用して模擬技術に深く飛び込む前に、ウィキペディアによってモックが意味するものを皆が知っていることを確認しましょう.

In object-oriented programming, mock objects are simulated objects that mimic the behavior of real objects in controlled ways, most often as part of a software testing initiative. A programmer typically creates a mock object to test the behavior of some other object, in much the same way that a car designer uses a crash test dummy to simulate the dynamic behavior of a human in vehicle impacts. The technique is also applicable in generic programming.
Wikipedia

💡— HTTPレベルのモック。

API世界では、mockの概念は上記の同じままのままです、しかし、moqとrinomockのようなモックアップ物にフレームワークを使用する代わりに、これはmockサーバを使用してされます.
モックサーバは予期しないエンドポイントに応答し、存在しないエンドポイントに対するエラーは、クライアントが無効なリクエストを送信した場合にも、現実的な検証エラーを提供することが多い.

模擬サーバの選択肢

モックサーバを作成するための選択肢のいくつかがありますが、それぞれのトレードオフでは、以下の短いオプションのリストをチェックすることができます.

Mock Server

Postman Mock Server

Nock

Prism

上記のすべてのオプションは素晴らしいツールであり、確実に期待通りに動作します.しかし、このポストの目的は、OpenAPIドキュメントを使用してモックサーバを構築する方法を示すことです.
それを念頭に置いて、ちょうどPrism 私たちはオープンAPIを使用して統合された統合を提供し、我々はそれを行うには任意のコードを書く必要はありません.

🙌 — プリズム入門

PRIXはOpenAPIドキュメントを使用してAPIのモッキングのためのパッケージのセットを集約するコマンドラインインターフェイスです.これはJavaScriptとNODEJSを使用して開発された、巨大なコミュニティとGithubリポジトリに多くの星があります.

始める

最後のポストでは、私はポストシリーズのコードでgithubリポジトリを使用しているので、その上で作業を続けて解決策を進化させましょう.
以下のコマンドを使ってプロジェクトにプリズムを追加しましょう.

yarn add @stoplight/prism-cli
# or
npm install --save @stoplight/prism-cli

プリズムのHTTPモックサーバは、任意のHTTPソリューションのように、API記述ドキュメントで記述されたエンドポイントと検証規則を提供することで、本当のWeb APIをシミュレートします.

応答発生

プリズムは、利用可能などんな情報に基づいても意味のある応答を返すようにします.これは、どんなOpenAPIドキュメントも使用することができますが、より良いドキュメントはより良い結果を提供することを意味します.あなたがプリズム決定エンジンがどう反応生成のために働くかを知りたいならば、あなたはこれをチェックすることができますlink .

応答生成戦略

プリズムには、2つの応答生成戦略、静的生成、および動的生成があります.

静的発電戦略

デフォルトでは、プリズムは静的生成戦略を使用して応答メッセージを作成します.

prism mock <path-to-openapi>

指定されたOpenAPIドキュメントがResponse Bodyの例を持っている場合、それを使用します.そうでなければ、応答体は、偽の応答を作成するためにスキーマオブジェクト全体を調べて作成されます.

ダイナミック生成戦略

データの正確な同じ部分に対して何度も何度もテストすることは堅牢なAPIを構築する最良の方法ではありません.実世界ではデータが動的であり、適切に扱うことができなければなりません.

prism mock <path-to-openapi> -d

ダイナミックモードでは、これらの型に応じてすべてのプロパティにランダムな値を生成することによってこれを解決します.また、書式のような他の情報は、これは、あなたのAPIがより記述的であることを意味します.

妥当性検査

API記述ドキュメントプリズムに基づいて、要求本体、ヘッダー、クエリパラメータのすべての種類の検証規則を考慮に入れることができますtype , format , maxLength .

👊 — プリズム入門

今、プリズム基本とどのように動作するかを知って、我々のAPIプロジェクトでそれを構成して、新しいモックサーバを始めましょう.
まず第一に、パッケージを変更する必要があります.JSONは以下の例のように見えます.2つの新しいコマンドモックとpremock.

{
  "name": "todoapi-spec",
  "version": "1.0.0",
  "description": "OpenAPI specification for TodoAPI",
  "main": "index.js",
  "author": "Nicolas Takashi",
  "license": "MIT",
  "scripts": {
    "premock": "yarn bundle",
    "mock": "prism mock ./bin/api.yaml -d",
    "bundle": "swagger-cli bundle specs/api.yaml -o ./bin/api.yaml -t yaml",
    "prelint": "yarn bundle",
    "lint": "spectral lint ./bin/api.yaml --ignore-unknown-format"
  },
  "dependencies": {
    "@openapitools/openapi-generator-cli": "^1.0.15-4.3.1",
    "@stoplight/prism-cli": "^4.0.0",
    "@stoplight/spectral": "^5.5.0",
    "swagger-cli": "^4.0.4"
  }
}

さて、以下のコマンドを実行してプリズムを起動し、コンソールを見て出力を見ます.

yarn mock

コンソール出力を見た場合は、localhost:4010 , そして今から、このプリズムサーバにAPIを呼び出すことができます.

swagger UIによるAPI呼び出しの作成

swagger UIを使ってリクエストを呼び出しましょうが、その前にAPIを変更しましょう.YAMLとサーバーセクションを追加します.

openapi: 3.0.0
info:
  title: Todo App API
  description: Todo App API.
  version: v1
  contact:
    email: '[email protected]'
    name: 'Nicolas Takashi'
servers:
  - url: http://127.0.0.1:4010
    description: Mock Server
tags:
  - name: Tasks
paths:
  '/tasks':
    $ref: './components/paths/tasks/task.yaml'
  '/tasks/{id}':
    $ref: './components/paths/tasks/task-by-id.yaml'
components:
  schemas:
    Task:
      $ref: 'components/schemas/task.yaml#/components/schemas/Task'
    PagedTask:
      $ref: 'components/schemas/pagedTask.yaml#/components/schemas/PagedTask'
    ProblemDetails:
      $ref: 'components/schemas/problemDetails.yaml#/components/schemas/ProblemDetails'

Swagger UIを見たら、以下のイメージなどの利用可能なサーバーのリストを持つ新しいドロップダウンに気づくでしょう.

最後には、少なくとも、タスクを作成しようとしてみましょうPOST /tasks 出力を見ます.

成功リクエスト

以来name が必要です、そして、我々はこのプロパティを送りました、あなたが以下のイメージで見ることができるように、要求は位置ヘッダーでHTTP作成された201を返します.

無効な要求

名前のないタスクを作成しようとした後、OpenAPIドキュメントで説明されているように、HTTP bad requestを取得します.

🏁結論

それは今日のすべての今、あなたはモックAPIについての基本を持っている、私は本当にすべての機能を理解し、どのようにあなたのクライアントにこの戦略を活用する方法を理解するためにプリズム公式ドキュメントをチェックすることをお勧めします.
APIの模擬は、APIの消費とシステムの統合の間に存在する可能性が非常に多くの問題を予測することができます.
Githubでプロジェクトをチェックすることができます.この投稿で実装された実装ですべてが更新されます.
私はあなたがそれを楽しんで、私はあなたのフィードバックを知っている、下記のコメントを共有し、お友達と共有してください.