swagger チュートリアル
スワッガーを使い始める

備考

はじめに - インストール - セットアップ（Node.jsでの開発）

前書き：

Swaggerは、REST APIを記述する形式の一連の規則/仕様です。コードジェネレータやエディタなどの正式な仕様を中心に、強力かつ積極的に開発されたツールのエコシステムを提供します。 Swaggerの最も重要な部分は、メソッド、パラメータ、モデルのドキュメントがサーバーコードに緊密に統合されているため、APIが常に同期していることです。ここでは、何がスウィガーなのかの簡単な概要を示すリンクがあります。

仕様書：

仕様は、JSONまたはYAMLで記述できます。そして、私たちはそれに応じてスワッガーを作っています.jsonまたはswagger.yamlファイル。オンラインエディタを使用してファイルを作成できます。仕様の構文を説明するリンクがあります： http : //swagger.io/specification/

スワッガーを使用する方法：

1. APIファーストアプローチ（トップダウンアプローチ）：スワッガーエディタを使用→スワッガー定義を書く→swagger-codegenとswagger-uiを使用してAPIを生成
2. サービスの第1のアプローチ（ボトムアップアプローチ）：スワッガーアノテーションを使用してJAX-RSリソースクラスを開発する→swaggerコアを使用してスワッガー定義を自動的に生成する→swagger-codegenとswagger-uiを使用してクライアントAPIとドキュメントを生成する。上記は、swagger mavenプラグイン中のmavenビルド中に行うことができます。

インストールとセットアップ

このセクションでは、swaggerをインストールし、swagger UIをセットアップし、それを使用してサーバー側とクライアントSDKを生成します。 Node Package Managerを使用してswaggerをインストールするには、次のコマンドを実行します。

npm install -g swagger

'-g'フラグを使用すると、モジュールがグローバルにインストールされます。次に、次のコマンドを使用してプロジェクトを作成します。

swagger project create <project-name>

これにより、ユーザーにREST APIを開発するためのフレームワークを選択するよう求められます。 Expressを同じものに対して選択することができます。これにより、以下の項目とそれぞれにREADME.mdファイルを含むプロジェクトディレクトリが作成されます。

• API /
  • コントローラ/
  • ヘルパー/
  • モック/
  • スワッガー/
• config /
• テスト/
  • API /
    • コントローラ/
    • ヘルパー
• app.js
• package.json

サーバーは基本的に準備ができており、このコマンドを使用してプロジェクトルートで実行することができます。

swagger project start

ホストサーバーがlocalhostとして設定されていて、 app.jsファイルでポート番号が変更されていない場合、サーバーはhttp://localhost:10010から開始されます。ここで、スワッガーUIを使用してREST APIをさらに開発できます。これは、以下を使用して新しい端末で開始することができます。

swagger project edit

これにより、無作為に生成されたポートのブラウザタブでスワッガーエディタが開きます。サンプルのhello GET要求は、すでにswagger.yamlファイルに存在しています。このファイルをさらに変更すると、サーバーはそれ自身で再起動します。

pathsセクションで、 x-swagger-router-controller使用される値は、controllersフォルダ内のjavascriptファイル名にする必要があります。サンプルとして、hello_world.jsがcontrollersディレクトリに存在する必要があります。また、 operationIdパラメータの値は、上記のjavascriptファイルの関数名を表します。これは、ビジネスロジックを記述する場所です。このように、私たちの手の込んだ設定は完了し、APIをさらに開発するために使用することができます。