oasis-gen

クイックスタート ​

このページでは、OpenAPI ドキュメントから型付きの API を呼び出すまでの手順を説明します。

Node.js 22 以降と TypeScript プロジェクトが必要です。生成されるファイルに必要な TypeScript の設定については、動作要件をご覧ください。

oasis-gen のインストール ​

sh
npm install --save-dev oasis-gen

ドキュメントの作成 ​

次の OpenAPI ドキュメントを openapi.yaml として保存します。このドキュメントには、ペットを返すか、ペットが存在しないときにエラーを返す操作が 1 つ記述されています。

yaml
openapi: 3.2.0
info: { title: Petstore, version: 1.0.0 }
servers:
  - url: https://api.example.com
paths:
  /pets/{petId}:
    get:
      operationId: getPet
      parameters:
        - { name: petId, in: path, required: true, schema: { type: integer } }
      responses:
        "200":
          description: The pet.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Pet" }
        "404":
          description: The pet does not exist.
          content:
            application/problem+json:
              schema: { $ref: "#/components/schemas/Error" }
components:
  schemas:
    Pet:
      type: object
      required: [id, name]
      properties:
        id: { type: integer }
        name: { type: string }
    Error:
      type: object
      required: [title]
      properties:
        title: { type: string }

クライアントの生成 ​

ドキュメントを変更するたびにクライアントを再生成できるよう、package.json にスクリプトを追加します。

json
{
  "scripts": {
    "generate": "oasis-gen openapi.yaml -o src/api.ts"
  }
}

次に、このスクリプトを実行します。

sh
npm run generate

これで、src/api.ts にすべての操作の型と fetch ベースの小さなランタイムが出力されます。このファイルには依存関係がないため、ほかにパッケージをインストールする必要はありません。

操作の呼び出し ​

ts
import { 
createClient
 } from "./api.ts";

const 
api
 = 
createClient
();

const 
res
 = await 
api
.
GET
("/pets/{petId}", { 
path
: { 
petId
: 1 } });
switch (
res
.
status
) {
  case 200:
    
console
.
log
(
res
.
data
.
name
);
                    
data: $Pet
    break;
  case 404:
    
console
.
log
(
res
.
data
.
title
);
                    
data: $Error
    break;
  default:
    
console
.
error
(
res
.
status
, 
res
.
data
);
                                  
data: unknown
}

操作は、HTTP メソッドとパステンプレートをドキュメントの記述どおりに指定して選択します。status を判定すると、data の型はドキュメントでそのステータスに対して宣言されているレスポンスに絞り込まれます。一方、default の分岐ではドキュメントで宣言されていないステータスを扱うため、data の型は unknown になります。その理由は厳密な型で説明しています。

次のステップ ​

  • 厳密な型：レスポンスとリクエストの型付けの仕組み
  • 操作の呼び出し：パラメーター、リクエスト本体、レスポンス、エラーの扱い方
  • 認証：ドキュメントの security で要求される資格情報の送信方法
  • レシピ：エラー時に例外を投げる方法、TanStack Query、モックなど