IXTの森

イギリス発保険のブロックチェーンカンパニーiX Technology Groupの情報と、プラットフォームのiXledger及びERC20トークンの$IXTに関する情報を発信していきます。

iXledgerのブログを要約と翻訳 - Creating an API, Helped By Swagger

テクノロジー

 

今回は以下の記事を翻訳、要約していきます。オリジナルの投稿はMohammed  Yafiiさん執筆です。

Creating an API, Helped By Swagger | iXledger

 

まあはっきり言って誰向け？？的な記事ですが、、。

ここで述べている技術を使ってQ4のサードパーティ向けAPI解放も予定通り進んでくれればいいですね。

 

要約

  • OpenAPIの仕様に準拠するためにSwaggerは便利なツールである
  • ローカルでも使用できる
  • Redocという類似のツールもあるが作者はSwaggerを好む

 

それでは本文です。

 

APIの仕様書を書くことは、やり方によっては恐ろしく時間がかかるプロセスになる可能性があります。プログラマーやアーキテクトの中には、コードを積極的に書く作業部分だけが好きな人もいれば、ドキュメントを徹底的に作ることを楽しむ人もいます。もちろん、APIを文書化することは、あなた自身の利益のためだけでなく、APIの消費者であろうと、それに貢献することが期待される人であろうと、あなたのAPIを使用したい人の利益のために重要です。

(補足)僕の経験では一般的にはドキュメント化は苦痛です。。

 

Swaggerとは

Swaggerは、OpenAPI仕様に準拠したAPIの設計、構築、文書化、テスト、標準化のためのツールを提供して、この一連のプロセスをより洗練させることができます。

Swaggerを使用して、オンラインのSwaggerEditorでYAMLファイルを入力するだけで、最新のAPIを設計して文書化することができます。

エディタはpetstoreからペットのGET、POST、PUT、DELETEの使い慣れたエンドポイントを文書化し、RESTfulなデザインのpetstore APIの設定例となるYAMLファイルを提供します。エディタの横にはSwagger UIがあります。これは、構造化された読みやすくインタラクティブな形式でAPIをレイアウトしています。

引用元：https://www.ixledger.com

 

Swaggerエディター

それぞれのメソッドを拡張して、説明、パラメータ、リクエストボディとレスポンスボディの例、レスポンスコードなど、より詳細な情報を表示することができます。

だから、もしあなたがこれらのいずれかを省略したら、必要な詳細を記述していないことに気づくでしょう。Open APIの仕様はこちら。

引用元：https://www.ixledger.com

 

 

SwaggerEditorの使用

SwaggerEditor / SwaggerUIの組み合わせは、一定のフィードバックを提供し、エディタで変更が加えられるたびにUIのライブアップデートを提供し、構成ファイルの出力を常に視覚化することができます。

これに加えて、SwaggerEditorは設定ファイルを書き出す際に、構文エラーがあるか、またはコンフィギュレーションの値がOpenAPIの仕様に適合していない時は発生したエラーを強調表示します。

私自身のバックグラウンドに基づくと、これは私にとって最も有用な機能でした。APIを設計する際にAPIの消費者の視点からより多くのことを考えるようになるだけでなく、個人的には、ウェブ上に散在する「良いREST APIデザインガイドライン」をすべて徹底的に調べることなく、うまく構造化されたAPIを作ることに関して様々な良いポイントを得ることができました。

APIを設計するときの正しい構造を見つけるために苦労してきた以前の経験からすると、APIを定義する設定ファイルを作成する際のヒントが提供されるのはとても有用です。 更に詳しく知りたい場合はOpenAPI仕様を参照することができます。私が設定ファイルを書いている間、REST APIの達人が私の隣に座っているような感じです！

ローカルホストでSwaggerを設定する

Swagger EditorはNodeJSを使用してローカルでダウンロードまたはWebで使用できます。

また、npmを使用してSwagger UIをインストールすることもできます。これにより、コード内でローカルに仕様を定義し、SwaggerUIにロードすることができます。

利用する場合はGitHubレポをチェックしてください。

 

ReDoc - Swaggerの代替

ReDocはSwaggerUIに似たクールなオープンソースツールで、APIのドキュメントを手助けし、OpenAPI仕様に準拠しています。

ReDocは、ドキュメントとやりとりするための3列のスタイルのインターフェイスを提供します。左側のナビゲーションパネル、中央のメソッドドキュメント、右側のパネル上のさまざまなコードサンプルが含まれます。

  

ここでライブデモをチェックすることができます。

 

RedocとSwaggerの違い

RedocとSwaggerの重要な違いは、SwaggerのUXはナビゲーションの上部にある低レベルのREST HTTP中心スタイルを強調しているのに対し(例: "HTTP:GET:/companies/{companyName}/employees/のような表記を中心に表示") 、RedocのUX設計ではインターフェースの説明を強調していることです（例えば、「全社員を取得」)

(API)を使う側の視点から見ると、これらの表現により、APIドキュメントを初めて見た際に必要な機能を簡単に見つけることができます。個人的には、SwaggerのREST HTTP中心スタイルで仕様書を作成した後、それをコード化してよりシームレスで構造化したので、私はRedocよりSwagger UXスタイルを好んでいます。