TypeSpecで出力先のフォルダ名などを変更する設定

TypeSpecを利用してOpenAPIの仕様書を作成すると、デフォルトではtsp-output/@typespec/openapi3/openapi.yamlのパスにファイルが出力されます。

これを任意のフォルダ（例えばswagger/spec.yaml）へ出力するように設定を変更する方法をまとめます。

最終的には設定ファイルを以下のように記述しました。

tspconfig.yaml

emit:
  - "@typespec/openapi3"

options:
  "@typespec/openapi3":
    emitter-output-dir: "{output-dir}"
    output-file: "{service-name}.{version}.spec.yaml"

output-dir: "{project-root}/openapi"

設定の変更

TypeSpecの設定はtspconfig.yamlに記載するか、CLIでのコンパイル実行時にフラグを指定することで変更できます。この記事では前者のtspconfig.yamlに記載する方法で説明したいと思います。

tspconfig.yamlファイルは、コンパイル時のエントリーポイントのパスに存在するものか、最も近い親フォルダに存在するものが参照されるようです。

出力フォルダを設定

デフォルトではファイルは{output-dir}/{emitter-name}というパスで出力されます。

Emitterというのは、TypeSpecで記述した仕様の出力フォーマットのようなものと私は認識しています。互換性があるものであれば、1つの記述でOpenAPIの仕様で出力したり、gRPCのProtobufで出力したりと出し分けられるようです。

今回想定しているユースケースはOpneAPIの仕様のみの出力なので、出力フォルダをemitter名を含まないopenapiフォルダとすることにします。

output-dirの設定

tspconfig.yamlに以下のように追記します。

tspconfig.yaml

emit:
  - "@typespec/openapi3"

+ output-dir: "{project-root}/openapi"

ここで{project-root}は組み込み変数で、tspconfig.yamlファイルのあるフォルダのパスを参照します。

ちなみに、output-dirは絶対パスにする必要があり、output-dir: "./swagger"などには設定できません。

これでopenapi/@typespec/openapi3/openapi.yamlにファイルが出力されるようになりました。

emitter-nameの設定

上記の設定では出力フォルダにまだemitter名のパスが残っているため、emitter名を省略するように設定します。

tspconfig.yaml

emit:
  - "@typespec/openapi3"

+ options:
+   "@typespec/openapi3":
+     emitter-output-dir: "{output-dir}"

output-dir: "{project-root}/swagger"

ここでは、OpneAPIの仕様書を出力する@typespec/openapi3のエミッターのオプションとして、出力先に大元のoutput-dirをそのまま指定しています。

この設定により、swagger/openapi.yamlに出力されるようになりました。

出力ファイル名を設定

次に出力されるファイル名がspec.yamlとなるように設定を変更します。

tspconfig.yaml

emit:
  - "@typespec/openapi3"

options:
  "@typespec/openapi3":
    emitter-output-dir: "{output-dir}"
+   output-file: "{service-name}.{version}.spec.yaml"

output-dir: "{project-root}/openapi"

ファイル名は、デフォルト値が{service-name}.{version}.openapi.yamlという形式なようです。なので、それを踏襲して最後のopenapi.yamlの部分のみspec.yamlへと変更しています。

これにより目的としていたopenapi/spec.yamlへの出力ができるようになりました。