1 Apidogを使い回す
2 本文では、
3 Apidogを利用し始めようとするユーザーに対して、
4 コア機能を紹介します。
5
6 30分間ほどの所要時間が必要です。
7
8
9 Apidogが選ばれた理由
10 開発チームがAPIの設計、
11 管理、
12 テストのために、
13 Postman、
14 Swagger、
15 Stoplight、
16 Jmeterなどのさまざまなツールを使用していることが多いことを観察しました。
17 ただし、
18 これらのツール間でのデータ同期とコラボレーションがないので、
19 効率が大幅に下がる可能性があります。
20
21
22 開発チーム全体が単一のAPIツール内ですべての作業をやり遂げるのは、
23 より良い解決策だろうと思っています。
24 APIドキュメントが定義されている限り、
25 バックエンド開発者はAPIを簡単に実装して自己テストを行い、
26 フロントエンド開発者はAPIを簡単に呼び出してMockデータを使用し、
27 テストエンジニアはAPIを直接テストしてテストケースを簡単に生成できたら、
28 チーム協同作業の効率が大幅に向上できるのでしょう。
29
30
31 これこそ、
32 私たちはApidogを始めたきっかけです。
33 Apidogは、
34 チームの協同作業のために設計されていて、
35 APIの設計、
36 開発、
37 テスト、
38 管理、
39 ドキュメント生成やMockなどのことが実現され、
40 今までにない包括的なAPIツールです。
41
42
43 Apidogとは
44 Apidogは、
45 API開発のためのオールインワンツールキットです。
46 チーム全体が協力して、
47 APIをより効率的かつ便利に作成するために開発されているものです。
48 チームの各メンバーは、
49 それを使って自分の問題解決を図ることができます。
50
51
52 apidog
53
54 Apidogは、
55 APIの設計と開発をユーザーインターフェイスより優先する開発アプローチ（いわゆるAPIファーストアプローチ）を採用しています。
56 このアプローチには、
57 次のようないくつかのメリットがあります。
58
59
60 Apidogを使用すると、
61 チームの各メンバーは同時に作業を進んでサービス間で合意を達成することで、
62 複数のAPIで同時に作業し、
63 開発速度を大幅に向上させることができます。
64
65 自動化は、
66 APIの定義ファイルのインポートツールを通して実現され、
67 APIの開発と実行に必要な時間を短縮できます。
68
69 直感的なデザインと十分に文書化されたAPIドキュメントにより、
70 開発者の優れたエクスペリエンスが保証されます。
71 また、
72 開発者が簡単にコードを使用・再利用し、
73 新しい開発者をオンボードし、
74 学習コストを減らすこともできます。
75
76 コードが書かれる前にも、
77 ほとんどの問題を解決することができるので、
78 APIをアプリケーションに統合する際に問題を発生することを防ぐこともできます。
79
80 API設計者：APIの作成
81 API設計者はApidogを使用して、
82 APIを視覚的に作成するか、
83 OpenAPIの仕様からインポートします。
84
85
86 OpenAPIの仕様からインポート
87 APIがOpenAPIまたはその他の形式で指定されている場合は、
88 Apidogにインポートすると、
89 簡単にデバッグ、
90 テスト、
91 またはMockすることができます。
92
93
94 Apidogのプロジェクトで インポートをクリックします。
95
96 Import
97
98 URLのインポートを選択して、
99 次のURLを貼り付けて、
100 提出をクリックします。
101
102 https://petstore.swagger.io/v2/swagger.json
103 apidog
104
105 JSONとYAMLファイルからのインポートも可能ですが、
106 Apidog、
107 HARなど、
108 他のAPI仕様の形式もサポートされています。
109
110
111 確認をクリックしてインポートします。
112
113 apidog
114
115 ここでApidogを使用してAPIを実行するか、
116 テストすることができます。
117
118 apidog
119
120 ヒント
121
122 データのインポートの詳細を ここで見る。
123
124
125 新しいAPIを作成
126 API設計者は非常に直感的なインターフェース内でAPIを作成できます。
127
128
129 新しいタブで 新しいAPI をクリックしてエンドポイントを作成します。
130
131 apidog
132
133 次に、
134 IDでユーザー情報を照会するためのAPIを指定します。
135 そのため、
136 次のフィールドをAPIに入力できます。
137
138 APIパス：
139 /users/{id}
140 名前：
141 IDでユーザー情報を取得
142 apidog
143
144 このAPIには、
145 QueryパラメータとBodyパラメータがありません。
146 ここで「Id」がPathパラメータとして認識されると、
147 「Request」の部分が完成しました。
148
149 Response 部分に移動して、
150 「OK (200)」でルートノードのフィールドタイプを「参照モデル → Schemas → ApiResponse」に変更します。
151
152 apidog
153
154 ここでAPIは、
155 次のような一般のJSON構造を生成しました。
156 全てのAPIも異なる「data」フィールドがあるため、
157 ルートノードに「data」と名付けられた子ノードを追加します。
158
159 apidog
160
161 「data」ノードのフィールドタイプを「参照モデル → Schemas → User」に変更します。
162
163 apidog
164
165 ここでResponseをうまく設定できました。
166 「data」構造内のデータを編集する場合は、
167 スキーマ参照を解除するか、
168 編集したいフィールドの参照を解除する必要があります。
169
170 apidog
171
172 ヒント
173
174 データSchemaの詳細を ここで見る。
175
176
177 Responseの例の部分に移動して、
178 例を追加をクリックします。
179
180 apidog
181
182 例の名称を「Success」に設定します。
183 ここで 自動生成をクリックして、
184 戻りデータがResponse構造に基づいて生成されます。
185 OK をクリックして例を追加します。
186
187 apidog
188
189 保存をクリックして、
190 APIの作成が完了しました。
191 ここでうまく設計されたAPIが手に入れましたよ。
192
193 apidog
194
195 バックエンド開発者：APIの開発とデバッグ
196 異なるチームは異なる開発アプローチを採用しています。
197 APIファーストを採用しているチームもありますし、
198 コードファーストを採用しているのもあります。
199 ただし、
200 チームがどの方法を採用していても、
201 バックエンド開発者はApidogを使用してAPIの開発とデバッグを簡単に実現できます。
202
203
204 コードの生成
205 APIが指定された場合、
206 スタブサーバーとクライアントSDKが簡単に生成されます。
207 APIページで コード生成 ボタンから すべてのコードを生成をクリックするだけです。
208
209 apidog
210
211 OpenAPI Generatorエンジンを利用して、
212 スタブサーバーとクライアントSDKを数十個の言語で生成できます。
213
214 apidog
215
216 ヒント
217
218 コード生成の詳細を ここで見る。
219
220
221 APIを実行
222 APIの開発が完了すると、
223 多くの場合ではバックエンドの開発者は、
224 APIが異なるパラメータで正確な結果を返すかをデバッグする必要があります。
225 Apidogを使用すると、
226 各APIをデバッグし、
227 正常に実行できることを簡単に確認できます。
228
229
230 先に作成したAPIのページで、
231 実行ボタンをクリックして 実行 タブに移動します。
232
233 apidog
234
235 「id」パラメータのパラメータ値で「1」を入力します。
236 ここで送信待ちのrequest URLの中の {id} は、
237 「1」に置き換えられます。
238
239 apidog
240
241 画面の右上角の 環境の管理ボタンをクリックします。
242
243 apidog
244
245 「テスト環境」に切り替えて、
246 次のURLを「Default Sever」サービスに貼り付けます。
247 その後、
248 環境を保存します。
249
250 https://mock.apidog.com/m1/352945-0-default
251 ヒント
252
253 環境管理の詳細を ここで見る。
254
255
256 apidog
257
258 そして、
259 「Testing Env」を選択すると、
260 先に設定したBase URLは、
261 送信待ちのすべてのrequestsの先頭に追加されます。
262
263 apidog
264
265 送信をクリックしてRequestを送信します。
266 APIのResponseは下の部分で表示されます。
267
268 apidog
269
270 デバッグ
271 APIの開発が環境を設定した後、
272 バックエンド開発者は、
273 期待のデータを返しているか、
274 APIが正しいロジックを実装しているかをテストする必要があります。
275
276
277 pathパラメータの値を「2」に設定して、
278 Requestを 送信します。
279
280 apidog
281
282 「.data.id should be integer」という警告が表示されます。
283 なぜかというと、
284 .data.idshouldbeinteger」という警告が表示されます。
285 なぜかというと、
286 .data.idはintegerである必要がありますが、
287 実際に返された$.data.idはStringになっているからです。
288
289 apidog
290
291 Apidogは、
292 APIの定義と実際のResponseが一貫しているかどうかを自動的に検証します。
293 正しくないデータタイプ、
294 定義されていない列挙値、
295 必須フィールドの欠落などの問題は自動的に検出されます。
296 バックエンド開発者は、
297 戻りデータの問題を簡単に検出できます。
298
299 APICaseを保存ボタンをクリックしてRequestを保存します。
300 当該RequestはAPIの子ディレクトリに保存され、
301 テストモジュールに参照されることができます。
302
303 apidog
304
305 apidog
306
307 変数の利用
308 Apidogでは、
309 変数がRequest間で再利用可能な値を格納するために利用されています。
310
311
312 環境変数は環境に繋がっています。
313 つまり、
314 特定の環境が選択された場合にのみアクセス可能です。
315 一方、
316 グローバル変数は、
317 すべての環境でアクセスできます。
318
319
320 Apidogの「環境の管理」セクションで環境変数を定義し、
321 {{variableName}}のように二重波括弧を使用して、
322 Requestで環境変数を参照できます。
323
324
325 例：
326
327 pathパラメータ「id」の値に{{Userid}}を入力します。
328
329 apidog
330
331 環境管理をクリックします。
332 Useridと名付けられた変数を新しく追加し、
333 ローカル値に「1」を記入して、
334 変数を保存します。
335
336 apidog
337
338 Requestを送信します。
339 Response - 実際のRequestの順にrequest URLを確認できます。
340 ここで {{Userid}} は ローカル値に置き換えられたことを確認できます。
341
342 apidog
343
344 ヒント
345
346 変数の詳細を ここを見る。
347
348
349 前処理
350 Apidogでは、
351 前処理はRequestを送信する前に実行される操作です。
352 これにより、
353 Requestが送信される前にRequestと環境変数を操作できます。
354
355
356 前処理の利用シーン：
357
358 Requestで利用されている変数の設定と編集
359 データ検証、
360 またはデータ変換の実行
361 Headerの追加と編集
362 ログ情報とデータのデバッグ
363 他のReuqestを行い、
364 そのResponseデータを変数への保存
365 Request URLの編集
366 これらの操作はJavaScriptに書き込まれ、
367 Postman SDKでRequest、
368 Responseオブジェクト、
369 環境変数、
370 及びグローバル変数にアクセスできます。
371 Scriptが追加されると、
372 Requestが送信されるたびに実行されます。
373
374
375 前処理のRequestパラメータ値を変更する例：
376
377 前処理タブをクリックし、
378 前処理を追加 ボタンをクリックして カスタムScriptを追加します。
379
380 apidog
381
382 次のScriptを カスタムScriptエリアに貼り付けます。
383
384 let Userid = parseInt(pm.environment.get("Userid"));
385 Userid = Userid + 1;
386 console.log(Userid);
387 pm.environment.set("Userid", Userid);
388 apidog
389
390 カスタムScript を 変数置換＆親を継承にドラッグして、
391 Requestを送信します。
392
393 apidog
394
395 送信した後、
396 {{Userid}}の値が2になったことを確認できます。
397 そして、
398 Requestを複数回送信する場合、
399 送信する度に、
400 {{Userid}} の値に1をプラスするようになります。
401
402 apidog
403
404 共通Script、
405 データベース操作及び待機時間は、
406 前処理に追加可能な項目です。
407
408 apidog
409
410 ヒント
411
412 Scriptの詳細を ここで見る。
413
414
415 フロントエンド開発者： APIのMock
416 APIのMockは、
417 テストと開発の目的で使用されるAPIのシミュレートされたバージョンです。
418 これにより、
419 開発者はライブAPIに依存せずにアプリケーションやサービスをテストでき、
420 送信のRequestに特定のResponseを返すように構成できます。
421
422
423 指定されたAPIに基づいて、
424 Apidogは設定なしでMockデータを自動的に生成できます。
425 それはフロントエンド開発者にとって非常に便利な機能です。
426
427
428 APIタブで ローカルMockを選択します.そして、
429 Click the URL/パラメータをクリックして、
430 「OK(200)」をコピーします。
431
432 apidog
433
434 ブラウザでURLを貼り付けます。
435 そして、
436 生成されたJSONが見えます。
437 そのデータはダイナミックで、
438 ページをリフレッシュする度にデータが変わります。
439
440
441 特に、
442 生成されたデータには、
443 「email」や「lastName」のような項目があります。
444 ご覧のように、
445 これらの値は非常に合理的で現実みたいものになります。
446 この機能は、
447 Apidogの スマートMockと言います。
448
449
450 apidog
451
452 変更タブの Response 部分で 「ApiResponse」Schemaの 参照を解除 します。
453
454 apidog
455
456 ノード内の各 Mock値を入力して、
457 APIを 保存 します。
458
459 code
460 200
461 type
462 JSON
463 message
464 Success
465 apidog
466
467 ブラウザでページを再読み込みすると、
468 JSONデータが更新され、
469 「code」、
470 「type」、
471 および「message」フィールドが設定に従って生成されます。
472 現在、
473 フロントエンド開発者は単にURLを使用して、
474 開発中のクライアントでデータを取得できるようになります。
475
476 apidog
477
478 Mock設定は、
479 Faker.jsをもサポートしています。
480 任意のFaker.js文法を選択してダイナミックのMockデータを生成できます。
481
482 apidog
483
484 MockのResponseを修正する必要がある場合、
485 設定 - 機能設定 - Mock設定 - デフォルトMockタイプの順にクリックし、
486 Response例を優先に切り替えます。
487 ApidogのMockエンジンは、
488 API Responseの例をMockのResponseとして使用します。
489
490 apidog
491
492 ヒント
493
494 ApidogのMock機能は、
495 クラウドMockもサポートし、
496 さまざまなRequestパラメータに対して異なるMock Responseを返したり、
497 Scriptを使用してMockのResponseを書き換えたり、
498 賢いMockマッチングルールをカスタマイズしたりすることができます。
499
500 Mockの詳細を ここでを見る。
501
502
503 QAエンジニア：APIのテスト
504 Apidogの自動テストモジュールにより、
505 QAエンジニアはAPIの定義またはAPIケースを参照して、
506 テストのシナリオを直接に生成できます。
507 データ駆動型テストをサポートし、
508 ダイナミックのテストデータを簡単に生成できます。
509 また、
510 アサーションと変数抽出機能により、
511 テストケースの作成を非常に簡単にしました。
512 ApidogはCI/CDもサポートしています。
513
514
515 アサーション
516 Apidogでは、
517 後処理でサーションを追加することができます。
518 また、
519 Postman SDKを使用してカスタムスScriptでアサーションステートメントを追加することもサポートしています。
520
521
522 Get user by id - Successという保存ケースに移動して、
523 後処理 タブで 後処理を追加 - アサーションの順にクリックします。
524
525 apidog
526
527 アサーションで次のパラメータを設定します：
528 Response JSON
529 $.code
530 Assertion
531 等しくない： 200
532 ヒント
533
534 JsonPathの詳細を ここで見る。
535
536
537 apidog
538
539 Reuqestを送信すると、
540 アサーション結果を確認できます。
541
542
543 Apidogは、
544 Response JSONから$.codeの値を取得して、
545 アサーションと比較します。
546 マッチングする場合、
547 アサーション結果は合格になります。
548
549
550 apidog
551
552 後処理では、
553 変数抽出, カスタムScript, 共通Script, データベース操作と 待機時間も追加されることができます。
554
555
556 MySQL、
557 SQL Server、
558 Oracle、
559 PostgreSQL、
560 およびClickHouseデータベースは、
561 Apidogでサポートされています。
562 SQLステートメントを実行でき、
563 SELECT結果を変数に抽出できます。
564 INSERT、
565 DELETE、
566 UPDATEなどの他のSQLも実行できます。
567
568
569 apidog
570
571 ヒント
572
573 データベース操作の詳細を ここで見る。
574
575
576 シナリオテスト
577 アサーションを書いた後、
578 複数のAPIケースを同じ単一のテストケースにインポートし、
579 1クリックで実行してテストレポートを生成します。
580
581
582 自動テストモジュールにアクセスして、
583 新規テストケースを作成します。
584
585 APidog
586
587 当該ケースの設定を終了してそれにアクセスします。
588 ステップを追加をクリックして、
589 APIテストケースからインポートするを選択します。
590
591 APidog
592
593 テストのステップとして、
594 保存したAPICaseを選択して、
595 「確認」をクリックしてインポートします。
596
597 APidog
598
599 テストケースを行うには、
600 実行ボタンをクリックします。
601 そして、
602 詳細なテストレポートが作成され、
603 各Requestの詳細を確認することができます。
604
605 apidog
606
607 失敗した項目で 詳細をクリックし、
608 Responseとアサーションを比較して、
609 うまく行かなかった原因をチェックできます。
610
611 apidog
612
613 apidog
614
615 ヒント
616
617 テストケースの詳細を ここで見る。
618
619
620 データ駆動型テスト
621 APIケースで変数が使用される場合、
622 データテーブルか「動的値」機能を使用して変数の値を自動的に生成するように設定できます。
623
624
625 テストデータをオンにして、
626 テストデータを管理するをクリックします。
627
628 apidog
629
630 変数とデータベースを追加し、
631 変数の値も設定します。
632 ここでCSVかJSONからインポートすることもサポートされます。
633 保存をクリックして、
634 テストデータの設定を保存します。
635
636 apidog
637
638 ここテストデータを利用するかを選択して 実行します。
639 変数の値は、
640 テストケースの反復で使用されます。
641
642 apidog
643
644 ヒント
645
646 テストデータの詳細を ここで見る。
647
648
649 CI / CD
650 Apidogはコマンドラインでの実行をサポートしています。
651 Apidog CLIをインストールした後、
652 apidog runコマンドを使用してコマンドラインのテストレポートを取得できます。
653 このコマンドは、
654 Jenkinsでも利用して、
655 CI/CDを実装できます。
656
657
658 テストケースで「CI/CD」をクリックします。
659
660 Apidog
661
662 テストのパラメータを設定して保存すると、
663 コマンドラインが生成されます。
664 ここで さらに詳しくをクリックしてApidog CLIをインストールします。
665
666 apidog
667
668 ヒント
669
670 CI / CDの詳細を ここで見る。
671
672
673 APIの設計者 & APIユーザー: APIドキュメント
674 APIの設計、
675 開発、
676 デバッグ、
677 テストが終了すると、
678 APIは、
679 他のユーザーが利用できるプロダクトになります。
680 Apidogは綺麗なAPIドキュメントを生成できるため、
681 開発チームはAPIを公開する時に役立ちます。
682
683
684 共有モジュールにアクセスし、
685 +新しい共有から共有項目を作成します。
686
687 apidog
688
689 APIドキュメント実行環境を選択すると、
690 APIドキュメントの利用者は、
691 ここで設定された環境を使用してAPIを実行できます。
692
693 apidog
694
695 「開く」をクリックして共有対象となるドキュメントをブラウザで開きます。
696
697 apidog
698
699 APIドキュメントが生成され、
700 インターネット上で共有できます。
701 また、
702 共有したWebサイトで「送信」することもできます。
703
704 APidog
705
706 コードのサンプル機能は、
707 APIのRequestコードを数十個のプログラミング言語で生成できます。
708 そして、
709 APIリーダーが生成されたコードで直接にAPIを呼び出すことが可能になります。
710
711 APidog
712
713 Responsesのコード生成 機能は、
714 Responseデータの構造に従ってコードを生成できます。
715 数十個のプログラミング言語がサポートされ、
716 API利用者は、
717 生成されたコードを直接に実装の段階で使用できます。
718
719 apidog
720
721 apidog
722
723 ドキュメント機能では、
724 カスタムドメイン、
725 上部のナビゲーション、
726 カタログのスタイル, コンテンツのフッターなど、
727 他にも多くのカスタム機能はサポートされています。
728
729 apidog
730
731 ベストプラクティス
732 1.Apidogでは、
733 API設計者(またはバックエンド開発者)がAPIの仕様を定義します。
734
735
736 2.開発チームは協力して、
737 ドキュメントをレビュー＆改善し、
738 APIユースケースの一貫性を確保します。
739
740
741 3.Apidogを使用すると、
742 フロントエンド開発者は自動的に生成されたMockデータで開発を開始でき、
743 手動でMockルールを作成する必要はありません。
744
745
746 4.バックエンド開発者は、
747 開発中にAPIユースケースを使用してデバッグできます。
748 デバッグ中にすべてのAPIユースケースが合格した場合、
749 開発完了。
750 また、
751 開発中にAPIの変更がある場合、
752 APIドキュメントもデバッグ中に自動的に更新され、
753 最小限の手間で適時にAPIメンテナンスを行えます。
754
755
756 5.デバッグ後、
757 バックエンド開発者はAPIユースケースとして機能を簡単に保存できます。
758
759
760 6.QAエンジニアは、
761 APIユースケースを使用してAPIを直接にテストできます。
762
763
764 7.すべてのAPIが開発されると、
765 QAエンジニア(またはバックエンド開発者)は、
766 テストケースとテストコレクション機能を使用して、
767 全面的に複数のAPIインテグレーションテストを実施できます。
768
769
770 8.フロントエンドとバックエンド開発の共同デバッグは、
771 両方のチームが同じなAPIの仕様に準拠しているため、
772 フロントエンド開発者がMockデータから実際のデータに切り替える時にも、
773 通常問題が発生しません。
774
775
776 9.API開発が完了すると、
777 Apidogは綺麗なAPIドキュメントを生成し、
778 開発チームがAPIを外部チームに簡単に公開できます。
779
780
781 上記は、
782 Apidogのコア機能と操作ガイドの概要です。
783 Apidogには、
784 開発チームがAPIを効率的に開発してデバッグするのに役立つ機能がたくさん備えていますので、
785 今すぐApodogの使用を開始して探索し始めましょう。
786
787
788
789
