TypeSpec OpenAPI を利用したopの取り扱い

背景

個人的には、OpenAPIの定義ファイルとして
Model層(Model + op) + OpenAPIの定義ファイルを分けて書くことを実施したいと思っていたが、
普通にnamespaceなどを利用しないで書いた場合に問題が生じる。
また、namespaceを利用してモデルを記載した場合も同様にmodel名にnamespaceがprefixがついてしまい、気持ちわるいと思った。

解決したい課題

1. opをnamespaceなしに記載した場合、openapiに定義されてしまう課題
2. namespaceを利用してmodelを定義した場合に、namespaceがprefixについてしまう

1. opをnamespaceなしに記載した場合、openapiに定義されてしまう課題

1-1. 課題

blog.tsp

model Blog  {}
model CreateBlogDTO {}

op createBlog(dto: CreateBlogDTO): Blog

@resource("/blogs")
interface BlogAPI {
   op create is createBlog;
}

上記でopenapiを作成した場合に、

openapi.yaml

paths:
  /:
      post: //blogs postと同じ
  /blogs:
      post: / postと同じ

上記のように意図しないschemaが生成されてしまう。

1-2. 回避策

namespaceを利用して、operationをまとめる。

blog.tsp

model Blog  {}
model CreateBlogDTO {}

namespace BlogOperations {
  op createBlog(dto: CreateBlogDTO): Blog
}

@resource("/blogs")
interface BlogAPI {
   @operationId("createBlog")
   op create is BlogOperations.createBlog;
}

上記を元に生成した場合は、意図してないschemaが生成するのを防げる。

openapi.yaml

paths:
  /blogs:
    post:

2. namespaceを利用してmodelを定義した場合に、namespaceがprefixについてしまう

2-1. 課題

blog.tsp

namespace BlogModule {
  model Blog  {}
  model CreateBlogDTO {}
}

openapi.yaml

components:
  schemas:
    BlogModule.Blog:
    BlogModule.CreateBlogDTO:

2-2. 回避策

namespaceを利用せずにglobalで記載する。

blog.tsp

model Blog  {}
model CreateBlogDTO {}

openapi.yaml

components:
  schemas:
    Blog:
    CreateBlogDTO: