DubboのSwaggerがここにあります！Dubbo-Api-Docsがリリースされました

著者| Ke Ran（Evil Shadow）
ソース| AlibabaCloudネイティブ公式アカウント

バックグラウンド

Swaggerは、RESTful Webサービスを生成、記述、呼び出し、および視覚化するための標準化された完全なフロントエンドフレームワークです。Swagger仕様は、徐々にOpenAPI仕様に進化しました。

Springfoxは、Swaggerを統合し、Sring MVC / Spring Webfluxに基づくSwagger記述ファイル生成フレームワークであり、Swaggerがインターフェースを表示および呼び出すことができるように、定義されたインターフェースを記述するいくつかの注釈を使用してSwagger記述ファイルを自動的に生成します。

多くの人がSwaggerとSpringfoxを聞いて使用したと思うので、ここでは繰り返しません。

Dubbo-Adminにはインターフェイステスト機能がありますが、インターフェイスの説明ドキュメントがないため、このテスト機能はインターフェイス開発者がインターフェイスをテストするのに適しています。他の人がこの関数を使用したい場合は、関数を使用してインターフェースをテストする前に、まずインターフェース開発者が作成したドキュメントまたはその他のメソッドを通じてインターフェース情報を理解する必要があります。

Dubboには、Swagger / Springfoxツールと同様に、ドキュメントを作成せずに発信者に直接インターフェイスを提供できるドキュメント表示およびテスト機能のコレクションがありますか？

 私は以前にいくつかの調査を行い、いくつかの同様のツールを見つけました：

• 一部はSpringfoxに基づいており、JSONをテキストフィールドに直接入力します。これは、Adminの現在のテスト機能に似ています。
• 一部は、SwaggerのJavaバージョンのOpenApI仕様生成ツールに直接基づいており、いくつかの基本的なデータタイプの単純なパラメーターをフォームアイテムとして表示できます。

それらにはすべて共通点が1つあります。それは、プロバイダーをWebプロジェクトに変えることです。もちろん、一部のプロバイダーはWebコンテナーをロードすることから開始され、一部のプロバイダーはWebプロジェクトを使用しているため、問題ではありません。

ただし、Web以外のプロバイダーもあります。ドキュメント用にWebプロジェクトに変換する必要がありますか？（Spring MVCなどのWebフレームワークの依存関係も多数導入する必要がありますか？）または、実稼働環境をパッケージ化するときに、その参照とコードを削除します。もっと簡単な方法はありますか？

OpenAPIにはRPC仕様はありません。SwaggerはOpenAPIの実装であるため、RPC関連の呼び出しはサポートされていません。SpringfoxはSwaggerを介して実装されたRESTfulAPIツールであり、RESTfulはWebベースであり、Dubboを直接使用することはできません。私たちはついにそれを自分たちで実装することを選びました：

• インターフェイス情報を説明する簡単なメモをいくつか提供します。
• プロバイダーの起動時に注釈が解析され、解決の結果がキャッシュされます。
• Dubbo-Api-Docsが使用するインターフェース情報を取得するためのいくつかのインターフェースをプロバイダーに追加します。
• Dubbo管理者側では、Dubbo汎化を使用して、HttpモードでDubboインターフェイスのゲートウェイを呼び出します。
• Dubbo管理者側でインターフェース情報の表示と呼び出しインターフェース機能を実現します。
• 以下の場合のパラメータはフォームアイテムとして直接表示され、その他のパラメータはJSONとして表示されます。
  • メソッドパラメータは基本的なデータタイプです
  • メソッドパラメータはBeanであり、Benaの属性は基本的なデータタイプです。
• サードパーティの依存関係はほとんどなく、それらのほとんどでさえプロジェクト自体で使用されます。
• プロファイルを介してロードするかどうかを決定できます。パッケージング中にプロファイルを変更するだけで、生産とテストを区別できます。プロファイルもすでに使用されています。

本日、お知らせいたします。DubboユーザーもSwaggerのような体験を楽しむことができます-Dubbo-Api-Docsがリリースされました。

前書き

Dubbo-Api-Docsは、dubboインターフェイスドキュメントを表示し、インターフェイスをテストするためのツールです。

Dubbo-Api-Docsの使用は、2つの主要なステップに分かれています。

1. dubboプロジェクトにDubbo-Api-Docs関連のjarパッケージを導入し、Swaggerと同様の注釈を追加します。

2. Dubbo-Adminでインターフェイスの説明とテストを表示します。

上記の2つの手順により、Swaggerのようなエクスペリエンスを楽しむことができ、本番環境でDubbo-Api-Docsのスキャンをオフにすることができます。

Dubbo-Api-Docsは現在、サービスノードに直接接続してサービスインターフェイスリストを取得しています。インターフェイスをテストするときは、直接または登録センターを介して接続できます。将来的には、登録センターを介してサービスリストを取得する方法が追加され、Dubboのアップグレード計画に従って新しい機能のサポートが追加され、コミュニティのニーズに応じて機能も追加されます。

サービスプロバイダーが開始された後、Dubbo-Api-Docsはドキュメント関連の注釈をスキャンして処理結果をキャッシュし、Dubbo-Api-Docs関連のDubboプロバイダーインターフェイスをいくつか追加します。キャッシュされたデータは、将来、Dubboメタデータセンターに配置される可能性があります。

現在のバージョン：2.7.8.1

<dependency>
    <groupId>org.apache.dubbo</groupId>
    <artifactId>dubbo-api-docs-annotations</artifactId>
    <version>${dubbo-version}</version>
</dependency>
<dependency>
    <groupId>org.apache.dubbo</groupId>
    <artifactId>dubbo-api-docs-core</artifactId>
    <version>${dubbo-version}</version>
</dependency>

クイックスタート

1.Dubbo-Api-Docsアノテーションがdubboプロバイダープロジェクトのメソッドパラメーターに追加されます

• dubboプロバイダーのインターフェイスとメソッドのパラメーターが別のjarプロジェクトにある場合は、dubbo-api-docs-annotationsをプロジェクトに導入します。
• dubboプロバイダープロジェクトはdubbo-api-docs-coreを導入します。
• アノテーション@EnableDubboApiDocsをプロバイダープロジェクトのプロジェクト起動クラス（@SpringBootApplicationでマークされたクラス）または構成クラス（@Configurationでマークされたクラス）に追加して、Dubbo ApiDocs機能を有効にします。

実稼働環境でのリソース占有の増加を回避するために、Dubbo-Api-Docsを有効にする別の構成クラスを作成し、それを@Profile（ "dev"）アノテーションとともに使用することをお勧めします。>
もちろん、Dubbo-Api-Docsは、プロジェクトの開始時にCPUリソースを少しだけ消費し、キャッシュに少しのメモリを使用します。将来的には、キャッシュの内容をメタデータセンターに配置することを検討します。

例 として、dubbo-api-docs-examplesプロジェクトのいくつかのサービスインターフェイスを取り上げます。

git clone -b 2.7.x https://github.com/apache/dubbo-spi-extensions.git

dubbo-spi-extensions / dubbo-api-docs / dubbo-api-docs-examplesディレクトリに入ります。

dubbo-api-docs-examplesには2つのサブモジュールがあります。

• examples-api：サービスインターフェイスとインターフェイスパラメータBeanを含むjarパッケージプロジェクト。
• 例-プロバイダー：スプリングブートスターターとサービスの実装を含むプロバイダーサーバー。

以下では、Dubbo-Api-Docsをこれらの2つのサブモジュールに追加します。

例-api：

Mavenの紹介：

<dependency>
    <groupId>org.apache.dubbo</groupId>
    <artifactId>dubbo-api-docs-annotations</artifactId>
    <version>2.7.8</version>
</dependency>

org.apache.dubbo.apidocs.examples.paramsには2つのBeanがあり、それらにdocs注釈を追加しましょう。

• QuickStartRequestBeanをパラメーターBeanとして、@ RequestParamを追加します。

public class QuickStartRequestBean {

  @RequestParam(value = "You name", required = true, description = "please enter your full name", example = "Zhang San")
  private String name;

  @RequestParam(value = "You age", defaultValue = "18")
  private int age;

  @RequestParam("Are you a main?")
  private boolean man;

  // getter/setter略...
}

• QuickStartRespBeanを応答Beanとして、@ ResponsePropertyを追加します。

public class QuickStartRespBean {

  @ResponseProperty(value = "Response code", example = "500")
  private int code;

  @ResponseProperty("Response message")
  private String msg;

  // getter/setter略...
}

デモンストレーションとして一部のインターフェイスのみを選択したため、これらのインターフェイスに関連するドキュメントの注釈が追加されました。

例-プロバイダー：

Mavenの紹介：

<dependency>
    <groupId>org.apache.dubbo</groupId>
    <artifactId>dubbo-api-docs-core</artifactId>
    <version>2.7.8</version>
</dependency>

デモンストレーションとしてインターフェイスを選択します。

org.apache.dubbo.apidocs.examples.api.impl.QuickStartDemoImplのquickStartメソッド。

QuickStartDemoImplは、apiパッケージにorg.apache.dubbo.apidocs.examples.api.IQuickStartDemoインターフェイスを実装します。

• QuickStartDemoImplの場合：

@DubboService
@ApiModule(value = "quick start demo", apiInterface = IQuickStartDemo.class, version = "v0.1")
public class QuickStartDemoImpl implements IQuickStartDemo {

  @ApiDoc(value = "quick start demo", version = "v0.1", description = "this api is a quick start demo", responseClassDescription="A quick start response bean")
  @Override
  public QuickStartRespBean quickStart(@RequestParam(value = "strParam", required = true) String strParam, QuickStartRequestBean beanParam) {
    return new QuickStartRespBean(200, "hello " + beanParam.getName() + ", " + beanParam.toString());
  }
}

この時点で、ドキュメント関連のコメントが追加されました。Dubbo-Api-Docsを起動しましょう。スプリングブートでスキャンできる限り、任意の場所に新しい構成クラスを追加します。

構成クラスDubboDocConfigをorg.apache.dubbo.apidocs.examples.cfgパッケージに追加します。

@Configuration
@Profile("dev")  // 配合 Profile 一起使用, 在 profile 为 dev 时才会加载该配制类
@EnableDubboApiDocs  // 开启 Dubbo-Api-Docs
public class DubboDocConfig {
}

これまでのところ、Dubbo-Api-Docs関連のものが追加されています。

dubbo-api-docs-examplesには 、より詳細な例があります。これについては、以下で詳しく説明します。Dubbo-Api-Docsを追加した後の効果の写真を見てみましょう。

2.プロバイダープロジェクトを開始します

• この例では、nacosを登録センターとして使用し、nacosをダウンロードして開始します。
• 上記の例では、examples-providerプロジェクトでorg.apache.dubbo.apidocs.examples.ExampleApplicationを起動します。

例-プロバイダーディレクトリ：

mvn spring-boot:run

3.dubbo-adminをダウンロードします

dubbo-adminウェアハウス

dubbo-adminを開始するには、開発ブランチのソースコードをダウンロードする必要があります。

git clone -b develop https://github.com/apache/dubbo-admin.git

4.アクセスdubbo-adminを開始します

開始するには、dubbo-adminの手順を参照してください。

1. 在 dubbo-admin-server/src/main/resources/application.properties 中修改注册中心地址
2. 编译 mvn clean package
3. 启动: 
mvn --projects dubbo-admin-server spring-boot:run
或者
cd dubbo-admin-distribution/target; java -jar dubbo-admin-0.1.jar
4. 浏览器访问: http://localhost:8080
5. 默认帐号密码都是: root

5.「インターフェースドキュメント」モジュールを入力します

• 「dubboproviderIP」と「dubboproviderport」にプロバイダーのマシンのIPとポートを入力し、右側の「loadinterfacelist」ボタンをクリックします。
• 左側のインターフェースリストにインターフェースリストをロードし、任意のインターフェースをクリックすると、インターフェース情報とパラメーターフォームが右側に表示されます。
• フォームの内容を入力したら、下部にあるテストボタンをクリックします。
• 応答部分は、応答例と実際の応答結果を示しています。

ソースコードリポジトリ

Dubbo-Api-Docsは機能に応じて分割され、2つのウェアハウスに分割されます。

1.dubbo-spi-extensions

dubbo-spi-extensionsウェアハウスアドレス

ウェアハウスには、dubboの非コア機能拡張機能がいくつか格納されています。Dubbo-Api-Docsはウェアハウスのサブモジュールです。ウェアハウスはDubbo 3.0の計画の一部であるため、Dubbo-Api-DocsはDubbo2.7.xに基づいて開発されています。はい、2.7.xブランチがリポジトリに追加され、Dubbo-Api-Docsはこのブランチの下にあります。
 
ウェアハウスには、Dubbo-Api-Docsドキュメント関連のコメント、コメントスキャン機能、および使用例が含まれています。

• dubbo-api-docs-annotations：ドキュメントによって生成された関連する注釈。dubbo apiのインターフェイスクラスとインターフェイスパラメータが実際の状況では個別のjarパッケージとして計画されることを考慮すると、注釈もjarパッケージとして独立しています。注意事項については、この記事の後半で詳しく説明します。
• dubbo-api-docs-core：注釈の解析、ドキュメント情報の生成、およびキャッシュを担当します。前述のDubbo-Api-Docs関連のインターフェイスもこのパッケージに含まれています。
• dubbo-api-docs-examples：使用例。

2.ダボ-管理者

Dubbo-管理倉庫の住所

ドキュメントの表示とテストは、dubboadminプロジェクトに配置されます。

注釈

• @EnableDubboApiDocs：注釈を構成し、dubbo apidocs関数を有効にします。

• @ApiModule：クラス注釈、ダボインターフェイスモジュール情報。インターフェイスモジュールの目的を示すために使用されます。
  • 値：モジュール名
  • apiInterface：プロバイダーによって実装されたインターフェイス
  • バージョン：モジュールバージョン
• @ApiDoc：インターフェイスの目的をマークするために使用されるメソッド注釈、ダボインターフェイス情報。
  • 値：インターフェース名
  • description：インターフェイスの説明（htmlタグを使用できます）
  • バージョン：インターフェースバージョン
  • responseClassDescription：応答データの説明
• @RequestParam：クラス属性/メソッドパラメーターの注釈、要求パラメーターのマーキング。
  • 値：パラメータ名
  • 必須：パラメーターを渡すかどうか
  • 説明：パラメータの説明
  • 例：パラメータの例
  • defaultValue：パラメーターのデフォルト値
  • 許容値：許容値。この属性を設定すると、インターフェイスにパラメータのドロップダウンリストが生成されます。
    • 注：この属性を使用すると、ドロップダウン選択ボックスが生成されます
    • booleanタイプのパラメーターはこのプロパティを設定する必要はなく、true / falseドロップダウンリストがデフォルトで生成されます
    • 列挙型のパラメータは自動的にドロップダウンリストを生成します。すべての列挙値を開きたくない場合は、このプロパティを個別に設定できます。
• @ResponseProperty：クラスプロパティの注釈、応答パラメータの注釈。
  • 値：パラメータ名
  • 例：例

注意してください

• 応答Bean（インターフェイスの戻りタイプ）はカスタムジェネリックをサポートしますが、ジェネリックプレースホルダーのみをサポートします。
• マップの使用について：マップキーは基本的なデータタイプのみを使用できます。マップのキーが基本データタイプでない場合、生成されたものは標準のjson形式ではなく、例外が発生します。
• 同期/非同期インターフェイスは、org.apache.dubbo.config.annotation.Service＃async / org.apache.dubbo.config.annotation.DubboService＃asyncから取得されます。

説明例

サンプルプロジェクトは、dubbo-spi-extensions / Dubbo-Api-Docsのdubbo-  api-docs-examplesディレクトリにあります：

• examples-api：サービスプロバイダーのインターフェイスクラスとパラメーターBeanを含むjarパッケージプロジェクト。
• examples-provider：dubbo-spring-boot-starterのプロバイダープロジェクトを使用します。レジストリはnacosを使用します。
• examples-provider-sca：spring-cloud-starter-dubboのプロバイダープロジェクトを使用し、レジストリはnacosを使用します。

手順の例

1. この例では、nacosを登録センターとして使用し、nacosをダウンロードして開始します。

2. example-providerとexamples-provider-scaのいずれかを開始します。もちろん、両方を開始することもできます。例-プロバイダーはポート20881を使用し、examples-provider-scaはポート20882を使用します。どちらのプロジェクトもスプリングブートプロジェクトであり、スタートアップクラスはorg.apache.dubbo.apidocs.examplesパッケージの下にあります。

3. スタートダボ-管理、ブラウザアクセス：http：// localhost：8080。

4. dubbo-adminに「interfacedocument」モジュールを入力します。

5. 「dubboproviderIP」と「dubboproviderport」にプロバイダーのマシンのIPとポートを入力し、右側の「loadinterfacelist」ボタンをクリックします。

6. 左側のインターフェースリストにインターフェースリストをロードし、任意のインターフェースをクリックすると、インターフェース情報とパラメーターフォームが右側に表示されます。

7. フォームの内容を入力したら、下部にあるテストボタンをクリックします。

8. 応答部分は、応答例と実際の応答結果を示しています。