Apicurio-studio: 仕様書全体でコンポーネントオブジェクトへの参照をサポートする

使用事例

これが解決する主なユースケースは、おそらく単一のファイル（またはファイルのセット）でデータ型定義を一元化する機能をユーザーに提供することです。 これらのデータ型は、中央の場所を参照することで、複数のAPI定義で活用できます。

考慮事項

外部参照をサポートするには、いくつかの機能強化が必要です。 順不同のリストは次のとおりです。

• データモデルライブラリ（現在はoai-ts-coreが、まもなくapicurio-data-modelsなります）は、プラグ可能な参照リゾルバーをサポートするように拡張する必要があります。 現在、これらのライブラリは内部参照のみを解決できます。 代わりに、ライブラリの利用者は、外部参照を正常に解決できるように、カスタム参照リゾルバーを提供できる必要があります。

• Apicurio Studioは、データ型の設計に重点を置いたエディターを備えた「データ型のみ」のスタイルのリソースをサポートする必要があります。 これにより、API設計とは独立してデータ型を作成/管理するためのより具体的なワークフローが可能になります。

• APIデザインエディターでタイプを設定する場合、ツールには外部リソースからタイプを選択する方法が必要です。 これらの外部タイプをユーザーに表示して選択するのに最適な方法を検討する必要があります。 APIデザインが他のリソース/ファイルを「インポート」して、UIがユーザーの選択肢を絞り込み、適切に表示できるようにする方法が必要な場合があります。 ある種の選択UIコントロールで使用可能なデータ型を表示するには、エディターが外部リソースをフェッチして解析する必要があることに注意してください。

• 進行中のデータ型リソースをAPIデザインの外部参照のソースとして使用できるかどうかを判断する必要がある場合があります。 言い換えれば、APIデザインで「スナップショット」データ型を参照できるようにする必要がありますか？ または、外部参照のソースとして使用する前に、データ型リソースを「最終」にする必要があります。 前者の場合、依存関係も確定するまでAPI設計を「確定」することはできません。 注：このコンセプト全体では、Apicurioにファイナライズリソースを実装する必要があります。

• Apicurioリソースを参照するときは、$ ref形式を決定する必要があります。 現在、すべてのAPIデザイン（または理論上のデータ型リソース）には一意のIDがありますが、作成時に生成される不透明なIDです。 そのIDは、現在、解決の目的でリソースを識別する唯一の一意の方法です。 リソースが完成したら（そのような概念をサポートしている場合）、リソースにもっと人間に優しい識別子を付与し、それを$ refURIで使用することができます。 何をするにしても、リソースをAPIレジストリ（別の将来の機能）に公開する場合、APIデザインの$ referenceは、APIレジストリによって適切な方法で解決可能である必要があることに注意してください。

$refの許容値に関する情報は次のとおりです。

$ refの値はURIですが、ネットワークロケーターではなく、識別子にすぎません。 これは、スキーマがそのURIでアクセス可能である必要はないことを意味しますが、アクセス可能である可能性があります。 基本的に、外部スキーマURIの処理方法はバリデーターの実装次第ですが、バリデーターが$ ref値で示されるネットワークリソースをフェッチすると想定するべきではありません。

参照の詳細については、 OpenAPI仕様とJSON参照RFCを参照してください。

（最初の外部参照ではなく）Apicurio内の別の仕様からのDataTypesへの参照の実装に優先順位を付けることは可能でしょうか？

私がこれを言う理由は、Swaggerの重要な使用法には、いくつかの相互参照機能が必要だからです。 たとえば、データ型（住所、人など）を共有するさまざまなサービスを実装しており、これらすべての仕様にApicurioを使用したいと考えています。 ただし、現時点では、相互参照を使用できないため、できません。

（最初の外部参照ではなく）Apicurio内の別の仕様からのDataTypesへの参照の実装に優先順位を付けることは可能でしょうか？

私がこれを言う理由は、Swaggerの重要な使用法には、いくつかの相互参照機能が必要だからです。 たとえば、データ型（住所、人など）を共有するさまざまなサービスを実装しており、これらすべての仕様にApicurioを使用したいと考えています。 ただし、現時点では、相互参照を使用できないため、できません。

同意しました、これは私たちをキラーアプリの領域に連れて行くでしょう。

@jsenkoレジストリの実装をまとめると、コミュニティからの明確な優先順位があるように見えます。 :)

私はこれを見たいと思っています。仕事でapicurioを使用すると、さまざまなチームにとって参照が非常に役立ちます。

これには少し時間がかかりましたが、外部参照は次のリリースであるベータ2.46から正式にサポートされる予定です（明日行われることを願っています）。 他のApicurioStudioドキュメントから現在のドキュメントにデータ型と応答をインポートするための新しいUIがあります。 さらに、検証が更新され、外部http / sおよびApicurio内部参照の解決がサポートされるようになりました。 これは、ドキュメント全体の参照を成熟してサポートするための良い第一歩となるはずです。