本文へ移動
Senri

OpenAPI

@senrijs/senri/openapi で、ルートの表から OpenAPI の文書を作る

import {  } from "@senrijs/senri/openapi";

export const  = ({
    "GET /users/:id": (
        {
            : .({ : ..() }),
            : ,                           // 200 の本文
            : { 404:  },             // ほかの status
            : { : "ユーザーを取る", : ["users"] },
        },
        ({  }) => (),
    ),
});

const  = (, { : { : "My API", : "1.0.0" } });
.("/openapi.json", () => );

既定では OpenAPI 3.1 の文書を作ります。

何から作るか

文書の中元にするもの
パスとメソッド表のキー(:id → {id})
パラメーターとリクエストの本文params・query・body のスキーマ。フォームで受けるルートは bodyType: "form"
レスポンスresponse(200)と responses(status ごと)に書いたものだけ
summary・tags などopenapi

ハンドラーの戻り値の型は、動いているときには分からないので、レスポンスには入りません。表にない app.get() などのルートも入りません。

スキーマを JSON Schema にする

Standard JSON Schema で変換します(Zod 4.2・ArkType 2.1.28 から)。

  • Valibot は @valibot/to-json-schema で包みます
  • 対応していないスキーマは、toJSONSchema で変換を渡せます
  • どちらもなければ、空のスキーマにして警告します

開発モードでは、ハンドラーの戻り値が response のスキーマに合わないと、ターミナルに警告を出します。応答は変えません。本番では確かめません。

オプション

名前

型

このページの内容