クイックスタート¶

Petstore デモ¶

このリポジトリには Swagger Petstore を使ったデモが含まれています。

1. Petstore サーバーを起動する¶

docker compose -f examples/petstore/docker-compose.yml up -d

API は http://localhost:8080/api/v3/ で利用可能になります。

2. API を登録する¶

papycli config add examples/petstore/petstore-oas3.json

3. コマンドを試す¶

# 利用可能なエンドポイントを表示する
papycli summary

# GET /store/inventory
papycli get /store/inventory

# パスパラメータを指定して GET する
papycli get /pet/99

# クエリパラメータを指定して GET する
papycli get /pet/findByStatus -q status available

# ボディパラメータを指定して POST する
papycli post /pet -p name "My Dog" -p status available -p photoUrls "http://example.com/photo.jpg"

# 生の JSON ボディで POST する
papycli post /pet -d '{"name": "My Dog", "status": "available", "photoUrls": ["http://example.com/photo.jpg"]}'

# 配列パラメータ（同じキーを繰り返す）
papycli put /pet -p id 1 -p name "My Dog" -p photoUrls "http://example.com/a.jpg" -p photoUrls "http://example.com/b.jpg" -p status available

# ネストしたオブジェクト（ドット記法）
papycli put /pet -p id 1 -p name "My Dog" -p category.id 2 -p category.name "Dogs" -p photoUrls "http://example.com/photo.jpg" -p status available

# DELETE /pet/{petId}
papycli delete /pet/1

4. タブ補完¶

シェル補完を有効化した後、タブ補完が利用できます：

$ papycli <TAB>
  get  post  put  patch  delete  config  spec  summary

$ papycli get <TAB>
  /pet/findByStatus  /pet/{petId}  /store/inventory  ...

$ papycli get /pet/findByStatus <TAB>
  -q  -p  -H  -d  --summary  --verbose  --check  --check-strict  --response-check

$ papycli get /pet/findByStatus -q <TAB>
  status

$ papycli get /pet/findByStatus -q status <TAB>
  available  pending  sold

$ papycli post /pet -p <TAB>
  name*  photoUrls*  status

$ papycli post /pet -p status <TAB>
  available  pending  sold

独自 API の追加¶

ステップ 1 — `config add` を実行する¶

papycli config add your-api-spec.json

このコマンドは以下を行います：

OpenAPI spec 内の $ref 参照を解決する
spec を papycli 内部の API 定義フォーマットに変換する
結果を $PAPYCLI_CONF_DIR/apis/<name>.json に保存する
$PAPYCLI_CONF_DIR/papycli.conf を作成・更新する

API 名はファイル名から導出されます（例：your-api-spec.json → your-api-spec）。

ステップ 2 — ベース URL を設定する¶

spec に servers[0].url が含まれている場合は自動で使用されます。含まれていない場合は $PAPYCLI_CONF_DIR/papycli.conf を編集して url フィールドを設定します：

{
  "default": "your-api-spec",
  "your-api-spec": {
    "openapispec": "your-api-spec.json",
    "apidef": "your-api-spec.json",
    "url": "https://your-api-base-url/"
  }
}

複数 API の管理¶

# 複数の API を登録する
papycli config add petstore-oas3.json
papycli config add myapi.json

# アクティブな API を切り替える
papycli config use myapi

# 登録済み API を削除する
papycli config remove petstore-oas3

# 登録済み API と現在のデフォルトを確認する
papycli config list

特定 API の独自 CLI を作成する¶

--api オプションを使うと、デフォルトを切り替えずに特定の登録済み API を指定して呼び出せます：

papycli --api petstore-oas3 get /pet/1

シェルエイリアス（または関数）と専用の補完スクリプトを組み合わせることで、各 API をタブ補完付きの独自 CLI として提供できます：

bash — ~/.bashrc に追加：

eval "$(papycli config completion-script --api petstore-oas3 bash)"
alias petstore-oas3='papycli --api petstore-oas3'

zsh — ~/.zshrc に追加：

eval "$(papycli config completion-script --api petstore-oas3 zsh)"
alias petstore-oas3='papycli --api petstore-oas3'

注意（bash の場合）： エイリアスの代わりにシェル関数を使いたい場合は、bash の関数名にハイフンを含めることができないため、ハイフンなしの API 名で登録する必要があります（例: petstore として登録し、petstore() { papycli --api petstore "$@"; } のように定義する）。