OpenAPI & サービスジェネレーター

一般的な@byeolnaerim/typed-rx-http、/nextまたは/rsocketのユーザーはこのスクリプトを実行しなくてもよく、openapi-typescriptをプロジェクトにインストールする必要もありません。

OpenAPIタイプ生成にはopenapi-typescript CLIが必要ですが、パッケージはこれを一般依存関係に入れません。typed-rx-http自体のdevDependencies.typescriptはTypeScript 6.0.3基準を維持し、OpenAPI auto nodeスクリプトでのみ別のnpx一時環境を使用します。

基本OpenAPI生成段階ではopenapi-typescriptと[email protected]を同時に実行するため、ユーザーのプロジェクトにインストールされたTypeScript/openapi-typescriptのバージョンを変更したり使用しません。

必要に応じて全コマンドをopenApiTypescriptCommandに固定できます。

または基本コマンドを構成するpackage versionだけを変更することもできます。

generatorの例にcommonServiceFileが登場する前にこのファイルを理解する必要があります。commonServiceFileはファイルを作成するオプションではなく、generated serviceが共通HTTP関数をimportするプロジェクト所有ファイルのパスです。ファイル名はrxjsHttpService.ts、commonService.tsなど自由に決められます。

最小完成形全体コード

以下のファイルはcreateHttpClientをプロジェクトで一度生成し、callApiとcallApiStreamをgenerated serviceが再利用できるようにexportします。キャッシュやセッション認証が必要ない場合はこの構造から始められます。

セッション/CSR/SSRキャッシュを含む全体コード

generated serviceがcallApiClientCacheまたはcallApiServerCacheを使用したり、Next.jsでリクエストごとのヘッダーとセッション認証を共通処理するには、次の全体形で拡張します。

基本設定は以下のファイルを生成します。

apiUnionArrays.tsはOpenAPIスキーマenumだけでなく、query、path、header、cookieパラメータenumのreadonly定数配列も生成し、配列queryパラメータのitems.enumも処理します。

SwaggerはSpringdoc、他のOpenAPIツール、または手動で作成したファイルでも構いません。WebFluxファンクショナルエンドポイントを使用する場合は webflux-fe-dev-assistantでSwagger文書を提供する方法も使用できます。

バックエンドエンドポイント、保存するswagger.json、タイプ/service出力パスとcommonServiceFileをプロジェクト構造に合わせて明示できます。

HTTPで文書を受け取れない環境では同じ出力オプションと共に generateSwaggerFromFileを使用できます。

commonServiceFileは生成されたserviceがcallApi、callApiStreamとキャッシュラッパーをimportするプロジェクト所有ファイルのパスです。generatorがこのファイルを生成したり上書きするオプションではありません。

rxjsHttpService.tsのようにcommonServiceFileで指定した共用ファイルはプロジェクトが直接管理します。autoと@types/autoの下の結果は文書が変更されると再生成されます。

サービスファイル名はURLの最初の2つのセグメントで、関数名は3つ目以降のセグメントで決まります。path variableはBy + PascalCase形式で関数名に含まれます。

生成されたserviceのqueryパラメータkeyはparams、path variableはpath、request bodyはbodyです。生成関数内部でそれぞれqueryString、pathVariable、bodyのServiceArgumentsに変換されます。