Softonic

OpenAPI 必須フィールドチェック

ステップ 1 / 2
次へ

API の記述を同僚、クライアント、ドキュメント生成ツールに渡す前に、必須フィールドが揃っているか確認しましょう。上にドキュメントを貼り付けると、バージョンフィールド、info.title、info.version、paths を確認し、不足しているものを一覧で示します。

必須フィールドの確認方法

  1. 1

    ドキュメントを貼り付ける

    作業中の段階でも構いません。仕様を JSON または YAML で貼り付けます。

  2. 2

    チェックを実行する

    結果のステップに進みます。不足している各フィールドは、それぞれ個別のエラーとして表示されます。

  3. 3

    不足分を追加する

    下のスニペットを使い、指摘されたフィールドをファイルに追加します。

  4. 4

    再チェックする

    更新した仕様を貼り付けて再実行し、エラーが表示されなくなるまで繰り返します。

必須となる 4 つの要素

フィールド 配置場所 例
バージョンフィールド トップレベル openapi: 3.0.3 または swagger: "2.0"
info.title info の内側 title: Orders API
info.version info の内側 version: 1.0.0
paths トップレベル 少なくとも 1 つのルートを含む paths:

info.version の値は、OpenAPI 仕様のバージョンではなく、自分の API のバージョンです。仕様のバージョンはすでに先頭に書かれているため、この項目を忘れる人が多くいます。

必須要素がすべて欠けている例

servers:
  - url: https://api.example.com

この小さなドキュメントには、必須要素が 1 つもありません。レポートには 3 件のエラーが表示されます。

検出内容 種別
Missing ‘openapi’ or ‘swagger’ version field. エラー
Missing ‘info’ object. エラー
Missing ‘paths’ object. エラー

info オブジェクトがまるごと欠けている場合、ツールはそのエラーを 1 件だけ報告し、title と version を個別には挙げません。info を両方のフィールドとともに追加すると、次の実行で、どちらかがまだ不足していれば報告されます。

最初のひな形

openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders:
    get:
      summary: List orders

このひな形は、必須フィールドのチェックをすべて通過します。名前を自分のものに置き換えて、そこから拡張してください。レスポンス、スキーマ、セキュリティは、このチェックの対象外です。

このチェックを実行するタイミング

新しい仕様をゼロから書き始めたとき、コードから生成したあと、別のツールに取り込む相手に渡す前に実行してください。多くのインポート機能は、最初に見つかった必須フィールドの欠落で短いメッセージを出して止まります。そのため、すべてをひとまとめに検出すると、やり取りの回数を減らせます。info.version を書き忘れたり、下書きの途中で paths を空のままにしたりしがちな初心者にとっても、有用な確認になります。

必須フィールドが通ったら、次に役立つのは info 直下の短い description、servers エントリ、そして各オペレーションの operationId です。これらはこのチェックでは確認されませんが、仕様を読みやすくし、クライアントコードへの変換も容易にします。

よくある質問

いいえ。openapi フィールドは、使用している仕様のバージョンを示します。info.version は、自分の API のバージョン（例: 1.0.0）です。

キーはオブジェクトとして存在している必要がありますが、このチェックではその中にルートがあることは求めません。公開前には実際のルートを追加してください。

title と version のチェックは、info オブジェクトが存在する場合にだけ実行されます。info を追加してから再実行すると、そのフィールドが揃っているかが分かります。

いいえ。ここで必須とされるのは、バージョンフィールド、info、title、version、paths だけです。オペレーション単位の詳細は確認されません。

関連ツール

Webpack設定ジェネレーター

素の JavaScript、React、Vue 向けに webpack 5 の webpack.config.js を生成します。TypeScript、Babel、CSS や Sass、画像、HtmlWebpackPlugin、開発サーバー、npm install のコマンドまでそろいます。

カラーティントジェネレーター

ベースカラーの明るい色合いを生成します。デザイン システム トークン、背景、ホバー状態を 3 ～ 20 段階でスケールします。

CMYK から RGB への変換

標準的な計算式で CMYK の割合をおおよその RGB 値と Hex 値に変換し、画面用にすばやく確認できます。

.gitignore ジェネレーター

Laravel、Node.js、Python、Rails のプロジェクト用除外ルールを組み合わせます。結果をコピーするか、.gitignore 入りの ZIP をダウンロードできます。個人用ルールは別に表示します。

16進数から10進数への変換ツール

16進数を10進数（10進法）に変換します。メモリアドレス、エラーコード、RGBチャンネル、任意精度の整数に対応します。

JSONからPythonデータクラスへの変換

JSONから、型ヒント、オプションフィールド、ネストされたクラス、およびdataclasses-jsonまたはPydanticサポートを備えたPythonデータクラスを生成します。

このツールは他の言語でも利用できます

使い方ガイドと活用例