不安定版のため予告なく破壊的変更が行われる可能性があります
概要
表題、および Playground の通り。
- OAS3.0.x専用（3.1以降とは互換性なし）
- APIおよびCLI
- CommonJS/ES Modules両対応
- カスタマイズ可能
- 変換を「型・キーワード毎に分割されたパーサー」で、出力を「 EJS テンプレート」で行い、いずれも自前のものに差し替えられる
- ライブラリ側で対応しなくてもユーザーが柔軟に出力内容を調整することが可能
- Paths Objectは扱わない
使用方法
READMEの通り。
参考
- OpenAPI Specification 3.0.3
- Components Object - OpenAPI Specification 3.0.3
- Schema Object - OpenAPI Specification 3.0.3
- Components Section (OAS3.0)
- Data Models (Schemas) (OAS3.0)
- JSON Schema Draft 2020-12
余談
OAS3.0→3.1は nullable の廃止といった破壊的変更を含む比較的大きなアップデートとなっており、OAS3.0のスキーマは JSON Schema Specification Wright Draft 00 を元にした独自仕様であるのに対し、OAS3.1のスキーマは JSON Schema Draft 2020-12 に準拠している。
3.1は2023年2月時点でSwagger UI/Editorが対応しておらず、自分の観測範囲ではほとんど使われていないことと、JSON Schema用のライブラリが転用できるため他の選択肢がありそうなことから、今回は考慮せず3.0専用とした。
なお、Swagger UI/Editorは2023Q1中にOAS3.1に対応するとのことなので、今後は移行が進むと思われる。
因みに本ライブラリは Next.js + React Hook Form との組み合わせで実戦投入済。（通信の方もOAS3.0ドキュメントを openapi2aspida に通して Aspida (@aspida/fetch, @aspida/swr) で利用している）