FIRST CHTools

FIRST CH TOOLS / 開発 / 73 OPENAPI DOC GENERATOR

OpenAPI → 日本語ドキュメント＆TypeScript型定義

OpenAPI / Swagger の仕様書（JSON・YAML）から、日本語のAPIドキュメント（Markdown）とTypeScript の型定義（.ts）を作ります。エンドポイント一覧・パラメータの表・リクエストとレスポンスの例・スキーマの表を書き出し、どちらもコピーかファイルで保存できます。仕様書はこのページの中だけで読み、端末の外へ送りません。

1 — 仕様書（OpenAPI / Swagger）

貼り付けるか、ファイルをこの欄へドロップします（20MBまで）。ファイルは端末の中で読むだけで、アップロードしません。
—
仕様の版
0
エンドポイント
0
スキーマ
—
生成にかかった時間

2 — APIドキュメント（Markdown）

エンドポイント一覧・パラメータの表・リクエストとレスポンスの例・スキーマの表を、この順に並べます。GitHub・Notion・Qiita・Zenn などにそのまま貼れます。

3 — TypeScript 型定義

スキーマは interface か type に、列挙は文字列リテラルの合併型に、nullable は | null になります。型の宣言だけで、実行するコードは含みません。
チェック結果
  • 仕様書を貼り付けるか、「サンプルを入れる」を押してください。

仕様書の解析もドキュメント・型定義の組み立ても、すべてこのページの中で動きます。貼り付けた仕様書・選んだファイルはサーバーへ送信しません（社内APIの仕様書でもそのまま使えます）。URLパラメータでは受け取りません。

How to Use

  1. 仕様書を入れるopenapi.yaml や swagger.json の中身を貼り付けるか、ファイルを開く・ドロップします。OpenAPI 3.0 / 3.1 と Swagger 2.0 の、JSON と YAML のどちらでも読めます。
  2. 言語と出力を選ぶドキュメントを日本語か英語か、レスポンス例を自動で作るか、エンドポイントごとの型も出すかを選びます。入れた時点で自動で生成されます。
  3. コピーか保存Markdown は .md、型定義は .ts で保存できます。型定義はフロントエンドの src/types/ などに置いて import します。

About This Tool

バックエンドが書いた OpenAPI（旧 Swagger）の仕様書から、読む人のための日本語のAPIドキュメントと、フロントエンドで使う TypeScript の型定義を一度に作るツールです。英語の Swagger UI を社内・取引先にそのまま渡しにくい、仕様書を外部のサービスにアップロードしたくない、という制作現場の事情に合わせ、解析から文字列の組み立てまでをこのページの中だけで行います。

ドキュメント（Markdown）には、ベースURL・エンドポイント一覧・認証方式に続けて、エンドポイントごとにパラメータの表（名前・場所・型・必須・説明）、リクエストボディ、レスポンスの表と例を並べ、最後に各スキーマのプロパティ表を付けます。タグがあればタグごとにまとめます。例は仕様書に書かれた example / examples を優先し、無ければスキーマの型・format・enum・default から作ります（その旨を見出しに書きます）。表の見出しや「必須」などの定型句が日本語になり、説明文そのものは仕様書の原文のままです（翻訳はしません）。

TypeScript の型定義は、components.schemas（Swagger 2.0 は definitions）を1件ずつ export interface か export type にします。required に無いプロパティは ? 付き、enum は "a" | "b"、allOf は &、oneOf / anyOf は |、nullable（3.1 は type: [..., "null"]）は | null、readOnly は readonly、format: binary は Blob です。説明・format・既定値・非推奨は JSDoc コメントで残るので、エディターの補完に出ます。エンドポイントごとの型は operationId（無ければメソッドとパス）から …Params・…RequestBody・…Response の名前で作ります。出力は TypeScript の --strict で型エラーが出ないことを、GitHub・Stripe の公開仕様書を含む実在の仕様書で確かめています。

できないこと: 別ファイル・URLを指す $ref（./schemas/user.yaml など）は読みに行かず、型を unknown にして知らせます。1ファイルにまとめた仕様書（bundle 済み）を入れてください。各言語のSDKや、実際にAPIを呼び出すクライアントコードは作りません（型の宣言だけです）。YAML は YAML 1.2 として読み、アンカー・エイリアス・マージキーにも対応します。書き方の誤りは行と桁を示して止まります。YAMLとJSONの変換・整形そのものは JSON ⇄ YAML 相互変換、JSONのレスポンスを表にするなら CSV/TSV ⇄ JSON 相互変換、Markdown の表の整形は Markdownテーブル整形 が対応します。

Other Tools