swaggerスワッガーを使い始める


備考

このセクションでは、魅力的なものの概要と、開発者がそれを使用する理由について概要を説明します。

また、大規模なテーマをスワッガー内で言及し、関連するトピックにリンクする必要があります。 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をさらに開発するために使用することができます。