APIを記述するための言語、TypeSpecを使ってOpenAPIドキュメントを生成してみる

これは、なにをしたくて書いたもの？

APIを記述するための言語として、TypeSpecというものがあるようなので1度どんなものか把握＆試しておきたいなということで。

TypeSpec

TypeSpecのWebサイトはこちらです。

typespec.io

GitHubリポジトリー。

GitHub - microsoft/typespec

ドキュメントはこちら。

Installation | TypeSpec

なのですが、概要を掴むにはMicrosoft Learnにあるドキュメントをまず読んだ方がいいかもしれません。

TypeSpec の概要 - TypeSpec とは - TypeSpec | Microsoft Learn

TypeSpecは、Microsoftが開発しているAPIを記述するための言語です。.tspという拡張子のファイルを作成するようです。

よくTypeSpecとOpenAPIドキュメント生成の組み合わせで名前を見かけるのですが、それはあくまで生成できるものの一種の
ようですね。

TypeSpecでAPI仕様を記述して、TypeSpecコンパイラーがエミッターと呼ばれるものを使用し、結果を生成します。
現時点でエミッターには以下があるようです。

• JSON Schema
• OpenAPI
• Protobuf（gRPC）（preview）
• Clients
  • クライアントコードの生成
  • JavaScript、Java、Python、C#が対象（いずれもpreview）
• Servers
  • サーバーサイドのコード生成
  • ASP.NET、JavaScriptが対象（いずれもpreview）

なのでTypeSpecでAPI仕様を書き、エミッターを使って別の仕様やコード生成を行えるといった代物のようです。
そして特にOpenAPIドキュメントが生成できるところに注目されやすいのかなと。

言語仕様としてはこちら。

Language Basics / Overview

ユースケースとしては、OpenAPIドキュメントの生成、バリデーションの定義、
シンタックスハイライトやコード補完などのツールのサポートが挙げられています。

ちなみに、OpenAPIドキュメントからTypeSpecへ変換することもできるようです。

OpenAPI3 to TypeSpec | TypeSpec

TypeSpecを使い始めるには、ひとまずNode.jsがあれば大丈夫そうです。

Installation | TypeSpec

実験的扱いでスタンドアロンバイナリーもあるようですが、現時点だとNode.jsで扱った方がよさそうですね。

環境

今回の環境はこちら。

$ node --version
v22.15.0


$ npm --version
10.9.2

TypeSpecを使ったプロジェクトの作成

では、TypeSpecを使ったプロジェクトの作成を行ってみます。

$ npx --package @typespec/compiler@latest tsp init

今回はTypeSpec 1.0.0-rc.1を使うことになります。

Need to install the following packages:
@typespec/compiler@1.0.0-rc.1
Ok to proceed? (y) y

通常は以下のコマンドを使うようですが、グローバルにインストールしたくなかったのでこうしました…。

$ npm install -g @typespec/compiler
$ tsp init

ここからは、対話形式でどのようなプロジェクトを作成するかを聞かれます。

プロジェクトテンプレート。

? Select a project template: (Use arrow keys)
❯ Generic REST API
  TypeSpec library
  TypeSpec emitter

プロジェクト名。コマンドを実行している親ディレクトリーの名前が、デフォルトで設定されるようになります。

? Enter a project name: (project-name)

つまり、新規プロジェクトを新規ディレクトリーから作成するコマンドではありません。

エミッター。今回はOpenAPIを選択。

? What emitters do you want to use?: (Press space to select, a to toggle all, i to invert selection and enter to proceed.)
❯ ◉ OpenAPI 3.1 document       [@typespec/openapi3]
  ◯ C# client                  [@typespec/http-client-csharp]
  ◯ Java client                [@typespec/http-client-java]
  ◯ JavaScript client          [@typespec/http-client-js]
  ◯ Python client              [@typespec/http-client-python]
  ◯ C# server stubs            [@typespec/http-server-csharp]

依存ライブラリーもインストールされ、これだけファイルが生成されました。

$ ll
合計 84
drwxrwxr-x  3 xxxxx xxxxx  4096  4月 27 15:20 ./
drwxrwxr-x 44 xxxxx xxxxx  4096  4月 27 15:16 ../
-rw-rw-r--  1 xxxxx xxxxx   102  4月 27 15:19 .gitignore
-rw-rw-r--  1 xxxxx xxxxx   872  4月 27 15:19 main.tsp
drwxrwxr-x 92 xxxxx xxxxx  4096  4月 27 15:20 node_modules/
-rw-rw-r--  1 xxxxx xxxxx 54752  4月 27 15:20 package-lock.json
-rw-rw-r--  1 xxxxx xxxxx   666  4月 27 15:19 package.json
-rw-rw-r--  1 xxxxx xxxxx   146  4月 27 15:19 tspconfig.yaml

作成されたファイルを見てみましょう。

package.json

{
  "name": "project-name",
  "version": "0.1.0",
  "type": "module",
  "peerDependencies": {
    "@typespec/compiler": "latest",
    "@typespec/http": "latest",
    "@typespec/rest": "latest",
    "@typespec/openapi": "latest",
    "@typespec/openapi3": "latest"
  },
  "devDependencies": {
    "@typespec/compiler": "latest",
    "@typespec/http": "latest",
    "@typespec/rest": "latest",
    "@typespec/openapi": "latest",
    "@typespec/openapi3": "latest"
  },
  "private": true,
  "packageManager": "npm@11.3.0+sha512.96eb611483f49c55f7fa74df61b588de9e213f80a256728e6798ddc67176c7b07e4a1cfc7de8922422cbce02543714367037536955221fa451b0c4fefaf20c66"
}

各パッケージのlatest指定にちょっと驚きましたが、インストール方法がこうだったからというわけではなく、
npm install -g @typespec/compilerの後にtsp initしても同じ結果になりました…。

TypeSpecの設定。

tspconfig.yaml

emit:
  - "@typespec/openapi3"
options:
  "@typespec/openapi3":
    emitter-output-dir: "{output-dir}/schema"
    openapi-versions:
      - 3.1.0

生成されたAPI仕様。

main.tsp

import "@typespec/http";

using Http;
@service(#{ title: "Widget Service" })
namespace DemoService;

model Widget {
  id: string;
  weight: int32;
  color: "red" | "blue";
}

model WidgetList {
  items: Widget[];
}

@error
model Error {
  code: int32;
  message: string;
}

model AnalyzeResult {
  id: string;
  analysis: string;
}

@route("/widgets")
@tag("Widgets")
interface Widgets {
  /** List widgets */
  @get list(): WidgetList | Error;
  /** Read widgets */
  @get read(@path id: string): Widget | Error;
  /** Create a widget */
  @post create(@body body: Widget): Widget | Error;
  /** Update a widget */
  @patch update(@path id: string, @body body: Widget): Widget | Error;
  /** Delete a widget */
  @delete delete(@path id: string): void | Error;

  /** Analyze a widget */
  @route("{id}/analyze") @post analyze(@path id: string): AnalyzeResult | Error;
}

コンパイルしてみましょう。

$ npx tsp compile .

このサンプルでは、このようなOpenAPIドキュメントが生成されました。

tsp-output/schema/openapi.yaml

openapi: 3.1.0
info:
  title: Widget Service
  version: 0.0.0
tags:
  - name: Widgets
paths:
  /widgets:
    get:
      operationId: Widgets_list
      description: List widgets
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WidgetList'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Widgets
    post:
      operationId: Widgets_create
      description: Create a widget
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Widget'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Widgets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Widget'
  /widgets/{id}:
    get:
      operationId: Widgets_read
      description: Read widgets
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Widget'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Widgets
    patch:
      operationId: Widgets_update
      description: Update a widget
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Widget'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Widgets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WidgetUpdate'
    delete:
      operationId: Widgets_delete
      description: Delete a widget
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: 'There is no content to send for this request, but the headers may be useful. '
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Widgets
  /widgets/{id}/analyze:
    post:
      operationId: Widgets_analyze
      description: Analyze a widget
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeResult'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
        - Widgets
components:
  schemas:
    AnalyzeResult:
      type: object
      required:
        - id
        - analysis
      properties:
        id:
          type: string
        analysis:
          type: string
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    Widget:
      type: object
      required:
        - id
        - weight
        - color
      properties:
        id:
          type: string
        weight:
          type: integer
          format: int32
        color:
          type: string
          enum:
            - red
            - blue
    WidgetList:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Widget'
    WidgetUpdate:
      type: object
      properties:
        id:
          type: string
        weight:
          type: integer
          format: int32
        color:
          type: string
          enum:
            - red
            - blue

それでは、このmain.tspを変更してAPI定義を行っていきましょう。

エディターの設定

その前に、エディターの設定を行おうかと思ったのですが。

標準ではVisual Stuido CodeとVisual Studio向けのExtensionがあるようです。

VS Code Extension | TypeSpec

Visual Studio Extension | TypeSpec

個人的にはEmacsが使いたいのですが、こちらのmodeはちょっとうまく組み込めませんでした…。

GitHub - pradyuman/typespec-ts-mode: Emacs major mode for TypeSpec (using tree-sitter)

TypeSpec - LSP Mode - LSP support for Emacs

仕方がないのでtypescript-modeでやることにしましたが、特に問題なかったです。

API仕様を記述して、OpenAPIドキュメントを生成してみる

それではAPI仕様を記述して、OpenAPIドキュメントを生成してみましょう。

お題は、少し前にMicroProfile OpenAPI 4.0をテーマにしたこちらの書籍を扱うREST APIの再現にしたいと思います。

WildFly 36 × SmallRye OpenAPI 4.0で出力するOpenAPIドキュメントのバージョンを3.1、3.0に切り替える - CLOVER🍀

作成したAPI仕様はこちら。

main.tsp

import "@typespec/http";
import "@typespec/openapi";

using Http;
using OpenAPI;

@service(#{ title: "My Sample REST API" })
@route("/api")
namespace SampleBookService;

model BookRequest {
  @doc("登録する書籍のタイトル")
  @example("Javaの本")
  @maxLength(100)
  title: string;

  @doc("登録する書籍の価格")
  @example(1500)
  @minValue(1)
  price: int32;

  @doc("登録する書籍の出版日")
  @example(plainDate.fromISO("2024-10-13"))
  publishDate?: plainDate; // optional
}

model BookResponse {
  isbn13: string;
  title: string;
  price: int32;
  publishDate?: plainDate;
}

@route("/books")
@tag("book")
namespace Books {
  @summary("登録された書籍をすべて返却する")
  @doc("登録された書籍を価格の降順にソートしてすべて返却する")
  @operationId("findAllBooks")
  @get
  op list(): {
    @body body: BookResponse[];
  };

  @summary("指定されたISBNに対応する書籍を取得する")
  @doc("指定されたISBNに対応する書籍を取得する")
  @operationId("findBookByIsbn13")
  @get
  op read(
    @path
    @minLength(14)
    @maxLength(14)
    @doc("ISBN")
    isbn13: string,
  ): BookResponse | NotFoundResponse;

  @summary("指定されたISBNに書籍を登録する")
  @doc("指定されたISBNに対応する書籍を登録する")
  @operationId("registerBook")
  op create(
    @path
    @minLength(14)
    @maxLength(14)
    @doc("ISBN")
    isbn13: string,

    @doc("登録する書籍データ") @body body: BookRequest,
  ): {
    @statusCode _: "201";
    @body body: BookResponse;
  } | {
    @statusCode _: "400";
    @body body: BadRequestResponse;
  };

  @summary("指定されたISBNに対応する書籍を削除する")
  @doc("指定されたISBNに対応する書籍を削除する")
  @operationId("deleteBookByIsbn13")
  @delete
  op delete(
    @path
    @minLength(14)
    @maxLength(14)
    @doc("ISBN")
    isbn13: string,
  ): NoContentResponse;
}

主に参照するドキュメントはこちらです。

TypeSpec for OpenAPI Developers | TypeSpec

ここでOpenAPI仕様での記述方法と、TypeSpecでの記述方法を合わせていきます。

最初に生成されたTypeSpecのサンプルのOperationの定義がこんな感じでしたが

interface Widgets {
  /** List widgets */
  @get list(): WidgetList | Error;
  /** Read widgets */
  @get read(@path id: string): Widget | Error;
  /** Create a widget */
  @post create(@body body: Widget): Widget | Error;
  /** Update a widget */
  @patch update(@path id: string, @body body: Widget): Widget | Error;
  /** Delete a widget */
  @delete delete(@path id: string): void | Error;

  /** Analyze a widget */
  @route("{id}/analyze") @post analyze(@path id: string): AnalyzeResult | Error;
}

ちゃんとsummaryやdescriptionを指定したり、operationIdも決めたりしようとするとちょっと長めになりました。

@route("/books")
@tag("book")
namespace Books {
  @summary("登録された書籍をすべて返却する")
  @doc("登録された書籍を価格の降順にソートしてすべて返却する")
  @operationId("findAllBooks")
  @get
  op list(): {
    @body body: BookResponse[];
  };

  @summary("指定されたISBNに対応する書籍を取得する")
  @doc("指定されたISBNに対応する書籍を取得する")
  @operationId("findBookByIsbn13")
  @get
  op read(
    @path
    @minLength(14)
    @maxLength(14)
    @doc("ISBN")
    isbn13: string,
  ): BookResponse | NotFoundResponse;

  @summary("指定されたISBNに書籍を登録する")
  @doc("指定されたISBNに対応する書籍を登録する")
  @operationId("registerBook")
  op create(
    @path
    @minLength(14)
    @maxLength(14)
    @doc("ISBN")
    isbn13: string,

    @doc("登録する書籍データ") @body body: BookRequest,
  ): {
    @statusCode _: "201";
    @body body: BookResponse;
  } | {
    @statusCode _: "400";
    @body body: BadRequestResponse;
  };

  @summary("指定されたISBNに対応する書籍を削除する")
  @doc("指定されたISBNに対応する書籍を削除する")
  @operationId("deleteBookByIsbn13")
  @delete
  op delete(
    @path
    @minLength(14)
    @maxLength(14)
    @doc("ISBN")
    isbn13: string,
  ): NoContentResponse;
}

@operationIdなどのOpenAPI用のものは、OpenAPIのimportおよびuseを
しておかないと使うことができません。

import "@typespec/openapi";

...

using OpenAPI;

あと、レスポンスボディに対するdescriptionはどうしてもうまく付けられませんでした…。ドキュメントを見ると@docで
よさそうなのですが…。

慣れない場合で、かつ既存のOpenAPIドキュメントがある場合は1度こちらで変換してみると参考になるでしょうね。

OpenAPI3 to TypeSpec | TypeSpec

では、記述したAPI仕様からOpenAPIドキュメントを生成してみます。

$ npx tsp compile .

結果はこちら

tsp-output/schema/openapi.yaml

openapi: 3.1.0
info:
  title: My Sample REST API
  version: 0.0.0
tags:
  - name: book
paths:
  /api/books:
    get:
      operationId: findAllBooks
      summary: 登録された書籍をすべて返却する
      description: 登録された書籍を価格の降順にソートしてすべて返却する
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BookResponse'
      tags:
        - book
  /api/books/{isbn13}:
    get:
      operationId: findBookByIsbn13
      summary: 指定されたISBNに対応する書籍を取得する
      description: 指定されたISBNに対応する書籍を取得する
      parameters:
        - name: isbn13
          in: path
          required: true
          description: ISBN
          schema:
            type: string
            minLength: 14
            maxLength: 14
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookResponse'
        '404':
          description: The server cannot find the requested resource.
      tags:
        - book
    post:
      operationId: registerBook
      summary: 指定されたISBNに書籍を登録する
      description: 指定されたISBNに対応する書籍を登録する
      parameters:
        - name: isbn13
          in: path
          required: true
          description: ISBN
          schema:
            type: string
            minLength: 14
            maxLength: 14
      responses:
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookResponse'
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TypeSpec.Http.BadRequestResponse'
      tags:
        - book
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BookRequest'
        description: 登録する書籍データ
    delete:
      operationId: deleteBookByIsbn13
      summary: 指定されたISBNに対応する書籍を削除する
      description: 指定されたISBNに対応する書籍を削除する
      parameters:
        - name: isbn13
          in: path
          required: true
          description: ISBN
          schema:
            type: string
            minLength: 14
            maxLength: 14
      responses:
        '204':
          description: There is no content to send for this request, but the headers may be useful.
      tags:
        - book
components:
  schemas:
    BookRequest:
      type: object
      required:
        - title
        - price
      properties:
        title:
          type: string
          maxLength: 100
          description: 登録する書籍のタイトル
          examples:
            - Javaの本
        price:
          type: integer
          format: int32
          minimum: 1
          description: 登録する書籍の価格
          examples:
            - 1500
        publishDate:
          type: string
          format: date
          description: 登録する書籍の出版日
          examples:
            - '2024-10-13'
    BookResponse:
      type: object
      required:
        - isbn13
        - title
        - price
      properties:
        isbn13:
          type: string
        title:
          type: string
        price:
          type: integer
          format: int32
        publishDate:
          type: string
          format: date
    TypeSpec.Http.BadRequestResponse:
      type: object
      required:
        - statusCode
      properties:
        statusCode:
          type: number
          enum:
            - 400
          description: The status code.
      description: The server could not understand the request due to invalid syntax.

ひとまずよさそうです。

コードフォーマットを行う場合はこちら。

$ npx tsp format '**/*.tsp'

Formatter | TypeSpec

スタイルガイドも見ておくとよいでしょう。

Style guide | TypeSpec

おわりに

APIを記述するための言語、TypeSpecを使ってOpenAPIドキュメントを生成してみました。

TypeSpecならではの書き方を覚えないといけないので、TypeSpecを書いてOpenAPIドキュメントを生成して、思ったとおりに
なっているか？といった確認を繰り返すことになりました。

記述方法が変わったので、そういうものですよね。

個人的にはOpenAPIのみに絞って見ると、MicroProfile OpenAPIのようなコードからOpenAPIドキュメントを生成するのと
あまり変わらない気がするのですが、そのようなフレームワーク自身がサポートしていない場合や、他のエミッターを利用できたり
するのでAPI仕様の管理をTypeSpecにまとめていくと良さが出るのかなと思います。

ひとまずTypeSpecがどういうものかは押さえられたのでよしとしましょう。