home/運営公式/

Swagger UIの使い方

APIドキュメント（Swagger UI）は、APIの入力項目と応答を調べ、実際にリクエストを送れる画面です。初めて使う場合は、読み取り用のAPIから試してください。

1. 画面を開く

通常のブラウザーで https://api.nijiurachan.net/ui を開きます。Cloudflareの確認画面が表示された場合は、画面の案内に従ってください。

操作一覧が読み込まれない場合は、まずAPIドキュメント自体とOpenAPIの取得が成功しているかを確認します。「Failed to fetch」は、入力したJSONが間違っていることだけを意味するエラーではありません。通信・CORS・Cloudflareの確認などでも発生します。

2. 操作の見方

操作名の左側には GET や POST などのHTTPメソッドが表示されます。操作をクリックすると詳細が開きます。

表示読むところ
メソッドとパス何を、どのURLで実行するか
Parametersパス・クエリ・ヘッダーに渡す値。required は必須
Request bodyPOSTなどで送るJSON本文
Example Value入力・応答の形を示す例。自分の環境で有効な値とは限らない
Schema型、必須項目、選べる値などの定義
Responses想定されるHTTPステータスと応答形式

パスの {threadId} などは、その場所を実際のIDに置き換えるという意味です。?apiVersion=... はクエリ、x-aimg-token はヘッダーです。JSON本文の中に書くだけでは、ヘッダーとして送信されません。

3. 読み取りAPIを試す

  1. 一覧で GET /capabilities を探して開きます。表示されない版では、仕様書に掲載されている読み取り操作を選んでください。
  2. Try it out を押します。
  3. 必須項目があれば入力し、Execute を押します。
  4. 実行後に表示される Request URL、HTTPステータス、Response body を確認します。
  5. JSONの apiVersion と capabilities を確認します。これは対象APIの版と対応機能を調べるための応答です。

操作の説明欄に載っている Responses の例と、実行後の実際の応答は別です。実行結果が200でも、本文がCloudflareのHTMLなどになっていないか確認してください。

同じ読み取りをターミナルから試す例です。

curl --fail-with-body --show-error --include \
  'https://api.nijiurachan.net/capabilities?apiVersion=2026-08-29'

ここで 403 とHTMLが返る場合は、ブラウザーでは通過できても、そのHTTPクライアントはCloudflare側で確認を求められている可能性があります。トークンを付けるだけで解決するとは限りません。

4. バージョンを指定する

確認した日付版は 2026-08-29 です。配信先の最新状況は応答の X-Api-Version とOpenAPIで確認してください。

  • apiVersion クエリがあれば、その指定が優先されます。
  • クエリがなければ X-Api-Version リクエストヘッダーを使います。
  • 両方なければ latest が使われます。

日付版の仕様書は OpenAPI JSON から読めます。Swagger UI自体のURLにクエリを付けるだけで、すべての実行リクエストに同じ版が渡るとは限りません。実行後の Request URL と応答ヘッダーで確認してください。

5. トークンが必要な操作

掲示板APIで使うヘッダー名は x-aimg-token です。現行OpenAPIでは aimgToken というAPIキー方式の認証が定義されています。アプリ用認証キーの一般配布は準備中です。

  1. Authorize を開き、aimgToken にその操作で使える発行済み資格の値だけを入力します。
  2. 対象の操作を開き、Try it out を押します。Parametersにも x-aimg-token がある場合は、生成されるcurlで実際のヘッダーを確認してください。
  3. X-Board-Key など、ほかの必須項目と本文を確認します。アプリ用APIには板のslugが必要です。

Bearer は付けません。GROWIのAccess Tokenや、CloudflareのCookieを入力するものでもありません。Authorizeは発行済み資格の送信設定で、資格を発行するボタンではありません。

通常の投稿APIでは承認済みアプリのcredentialを使えます。一方、接続済み一覧など承認元ブラウザーのトークンが必要な操作では、アプリ資格を代用できません。開始・交換APIは既存credentialの認証ではなく、登録内容とPKCEなどを検証します。

トークン取得とアプリ開発上の制約は アプリ開発者向け認証ガイド を読んでください。

6. 投稿・削除を試す前に

Swagger UIの Execute は、実際のAPI呼び出しです。POST・PUT・DELETEなどを実行すると、投稿・更新・削除が起きる場合があります。画面上の例を送信するだけの練習モードではありません。

投稿にはトークン以外にAltchaの解や添付の準備などが必要です。Example Valueをそのまま送らず、対象操作の必須項目を確認してください。送信結果が分からない場合は、重複投稿を避けるため無条件に再送しないでください。

7. 問い合わせるとき

Request URL、HTTPメソッド、APIバージョン、HTTPステータス、エラーコードを控えて、問い合わせ・不具合報告へ連絡してください。

生成されたcurl例やスクリーンショットには、入力したトークンが含まれることがあります。共有前に x-aimg-token、Cookie、認証ヘッダーの値を伏せてください。

API利用ガイド / 運営公式トップ / 更新日：2026年9月15日