CLI と API

CLI

oasis-gen <SPEC> [-o <FILE>] [--lang <LANG>]

引数	意味
`SPEC`	OpenAPI ドキュメントの JSON または YAML ファイル、あるいは標準入力を表す `-`
`-o`、`--output FILE`	標準出力の代わりに `FILE` へ出力
`-l`、`--lang LANG`	生成対象の言語。現在は `typescript`（既定値）のみ
`-h`、`--help`	ヘルプの表示
`-V`、`--version`	バージョンの表示

oasis-gen は、ほかのローカルファイルへの $ref をたどります。参照先は参照元のドキュメントからの相対パスとして解決されますが、ドキュメントを標準入力から読み込んだときは、カレントディレクトリーからの相対パスとして解決されます。
ドキュメントが不正であるなどのエラーが発生すると、oasis-gen は標準エラー出力に error: ... を出力し、終了ステータス 1 で終了します。
出力されるコードは Generated by oasis-gen ... Do not edit. という行で始まります。

動作要件

Node.js 22 以降が、CLI と生成されるクライアントの両方に必要です。なお、クライアントはブラウザー（Chromium、Firefox、WebKit で検証）や Bun でも動作します。
TypeScript 5.0 以降が必要です。生成されるファイルには lib の ES2022 以降が必要であり、さらに fetch、Request、Response の型定義として lib の dom または @types/node のいずれかが必要です。
生成されるファイルは TypeScript の消去可能な構文（erasable syntax）のみを使用しているため、Node.js の Type Stripping（Node.js 22.18 以降では既定で有効）でもそのまま実行できます。

このサイトのコード例では ./api.ts をインポートしています。このインポートには、allowImportingTsExtensions（Vite のテンプレートでは設定済み）または Node.js の Type Stripping が必要です。どちらも使わないときは、モジュール解決の方式に合わせて ./api.js または ./api をインポートしてください。

インストール

npm パッケージには、macOS（arm64、x64）、Linux（arm64、x64）、Windows（arm64、x64）向けのビルド済みバイナリーが含まれています。Linux 向けのバイナリーは静的リンクされているため、glibc と musl のどちらの環境でも動作します。npm は、お使いのプラットフォーム向けのバイナリーのみをインストールします。また、GitHub の各リリースにもアーカイブが添付されています。代わりにソースからビルドするときは、次のコマンドを実行してください。

cargo install --git https://github.com/22mb/oasis

API

生成されるファイルからは、次の要素がエクスポートされます。

エクスポート	説明
`createClient(options?)`	クライアントを作成する関数。操作の呼び出しを参照
`auth(credentials)`	ドキュメントの `security` の指定に従って資格情報を送信するミドルウェア。認証を参照
`DecodeError`	レスポンス本体が `Content-Type` と一致しないときに投げられるエラー。エラーを参照
`Pet` や `AccountRequest` などのスキーマ型と `Kind` などの列挙値	スキーマを参照
`paths`	パスとメソッドごとの、すべての操作の入力、レスポンス、各レスポンスが対象とするステータスコード
`schemas`、`components`	ドキュメントのスキーマ（名前ごと）。スキーマを参照
`ApiResponse<Operation>`	`paths` 内の操作から導出される、呼び出し結果の型
`Client<Paths>`、`ClientOptions`、`RequestOptions`	クライアント本体、クライアントのオプション、呼び出しごとの fetch オプション
`Middleware`、`MiddlewareContext`、`OperationInfo`	ミドルウェアと、ミドルウェアが受け取る情報。ミドルウェアを参照
`Credential`、`SecurityRequirement`、`SecuritySchemeName`	`auth` で使用される型
`ServerSentEvent`	`text/event-stream` レスポンスの 1 項目（`{ data, event?, id?, retry? }`）

`ClientOptions`

オプション	型	説明
`baseUrl`	`string`	ドキュメント内のすべてのサーバーを置き換えるベース URL
`headers`	`HeadersInit`、またはそれを返す関数（非同期関数も可）	すべてのリクエストで送信されるヘッダー
`middleware`	`Middleware[]`	すべてのリクエストをラップするミドルウェア（先頭の要素が最も外側）
`fetch`	`(request: Request) => Promise<Response>`	グローバルな `fetch` の代わりに呼び出される関数

`Middleware`

type Middleware = (
  request: Request,
  next: (request: Request) => Promise<Response>,
  context: { operation: OperationInfo },
) => Promise<Response>;

`OperationInfo` のフィールド	型	内容
`method`	`string`	呼び出しで使われたとおりの HTTP メソッド
`path`	`string`	`/pets/{petId}` などのパステンプレート
`operationId`	`string`（省略可能）	`operationId`（ドキュメントに記述があるとき）
`security`	`SecurityRequirement[]`	適用されるセキュリティ要件（ドキュメントでの記述順）

`Credential`

type Credential =
  | string
  | ((
      scopes: string[],
      context: MiddlewareContext,
    ) => string | undefined | Promise<string | undefined>);

undefined または "" は、その資格情報が利用できないことを表します。また、auth には Credential の代わりに undefined を渡すこともできます。

結果の型付け

ApiResponse には、paths から取得した操作の型を渡します。

import type { ApiResponse
, paths } from "./api.ts";

type GetPet
 = ApiResponse
<paths["/pets/{petId}"]["GET"]>;

CLI と API ​

CLI ​

動作要件 ​

インストール ​

API ​

ClientOptions ​

Middleware ​

Credential ​

結果の型付け ​