vscode-httpyac-config

VSCode httpYac 設定

このスキルについて

httpYac を使用して、API ドキュメントを実行・テスト可能な .http ファイルに変換します。このスキルでは、スクリプト、認証、環境管理、CI/CD 連携を備えた、本番環境で使える API コレクションを作成するためのワークフローを案内します。

このスキルを使用する場面

• API ドキュメント → 実行可能ファイル：API 仕様（Swagger、Postman、ドキュメント）を httpYac 形式に変換する場合
• 認証の実装：OAuth2、Bearer トークン、複雑な認証フローを設定する場合
• 大規模なコレクション：複数ファイル構成で 10 個以上のエンドポイントを整理する場合
• リクエストの連鎖：リクエスト間でデータを受け渡す場合（ログイン → トークンを使用 → 作成 → 更新）
• 環境管理：開発／テスト／本番環境を切り替える場合
• チームのワークフロー：認証情報を安全に扱いながら、Git ベースで共同作業する場合
• CI/CD 連携：GitHub Actions、GitLab CI などでテストを自動化する場合

期待される成果

• ✅ httpYac 構文が正しい、動作する .http ファイル
• ✅ 環境に基づく設定（.env ファイル、.httpyac.json）
• ✅ 安全な認証情報管理（シークレットを Git に含めない）
• ✅ リクエストの連鎖とレスポンスの検証
• ✅ ドキュメントを備えた、チームですぐに使える構成
• ✅ CI/CD パイプラインとの連携（任意）

---

基本的なワークフロー

フェーズ 1：調査と計画

目的：API の構造を把握し、ファイル構成を提案します。

主な確認事項：

1. エンドポイントはいくつありますか？（20 個未満＝単一ファイル、20 個以上＝複数ファイル）
2. 認証方式は何ですか？（Bearer、OAuth2、API キー、Basic Auth）
3. 必要な環境はいくつですか？（開発、テスト、ステージング、本番）
4. 既存のドキュメントはありますか？（Swagger、Postman コレクション、ドキュメント URL）

ユーザーに構成を提案：

Identified API modules:
- Authentication (2 endpoints)
- Users (5 endpoints)
- Articles (3 endpoints)

Recommended: Multi-file structure
- auth.http
- users.http
- articles.http

Proceed with this structure?

📖 詳細ガイド：references/WORKFLOW_GUIDE.md

---

フェーズ 2：テンプレートを使ったファイル作成

🚨 必須：必ず assets/ ディレクトリのテンプレートから始めてください。

テンプレートの使用手順：

1. assets/http-file.template を読みます
2. 構成をコピーして、対象ファイルに貼り付けます
3. {{PLACEHOLDER}} 変数を置き換えます
4. API 固有のリクエストを追加します
5. references/SYNTAX.md に照らして構文を確認します

利用可能なテンプレート：

• assets/http-file.template → .http ファイルの完全な構成
• assets/httpyac-config.template → 設定ファイル
• assets/env.template → 環境変数

作成する主なファイル：

• .http ファイル → API リクエスト
• .env → 環境変数（Git の追跡対象外）
• .env.example → プレースホルダーを含むテンプレート（コミット対象）
• .httpyac.json → 設定（任意）

📖 ファイル構成ガイド：references/WORKFLOW_GUIDE.md#phase-2

---

フェーズ 3：認証の実装

API の種類に応じてパターンを選択：

API の種類	パターン	参照先
静的トークン	シンプルな Bearer	references/AUTHENTICATION_PATTERNS.md#pattern-1
OAuth2 認証情報	トークンを自動取得	references/AUTHENTICATION_PATTERNS.md#pattern-2
トークンの更新	自動更新	references/AUTHENTICATION_PATTERNS.md#pattern-3
API キー	ヘッダーまたはクエリ	references/AUTHENTICATION_PATTERNS.md#pattern-5-6

簡単な例：

# @name login
POST {{baseUrl}}/auth/login
Content-Type: application/json

{
  "email": "{{user}}",
  "password": "{{password}}"
}

{{
  // Store token for subsequent requests
  if (response.statusCode === 200) {
    exports.accessToken = response.parsedBody.access_token;
    console.log('✓ Token obtained');
  }
}}

###

# Use token in protected request
GET {{baseUrl}}/api/data
Authorization: Bearer {{accessToken}}

📖 すべてのパターン：references/AUTHENTICATION_PATTERNS.md パターンの検索：grep -n "Pattern [0-9]:" references/AUTHENTICATION_PATTERNS.md

---

⚠️ 重要な構文ルール

🎯 変数の管理（最もよくある間違い）

1. 環境変数（.env ファイルから）

@baseUrl = {{API_BASE_URL}}
@token = {{API_TOKEN}}

✅ ファイルの先頭では @variable = {{ENV_VAR}} 構文を使用します

2. ユーティリティ関数（スクリプトブロック内）

{{
  // ✅ CORRECT: Export with exports.
  exports.validateResponse = function(response, actionName) {
    return response.statusCode === 200;
  };
}}

###

GET {{baseUrl}}/api/test

{{
  // ✅ CORRECT: Call WITHOUT exports.
  if (validateResponse(response, 'Test')) {
    console.log('Success');
  }
}}

3. レスポンスデータ（レスポンス後のみ）

GET {{baseUrl}}/users

{{
  // ✅ Store for next request
  exports.userId = response.parsedBody.id;
}}

❌ 禁止事項

{{
  // ❌ WRONG: Don't use exports/process.env for env vars
  exports.baseUrl = process.env.API_BASE_URL;  // NO!

  // ❌ WRONG: Don't use exports when calling
  if (exports.validateResponse(response)) { }  // NO!
}}

🔍 作成後のチェックリスト

• テンプレートをベースとして使用
• リクエスト間に ### 区切りを使用
• 変数：@variable = {{ENV_VAR}}
• 関数をエクスポート：exports.func = function() {}
• エクスポートなしで関数を呼び出す
• .env.example を作成
• .http ファイルにシークレットがないことを確認

📖 構文の全容：references/SYNTAX.md 📖 よくある間違い：references/COMMON_MISTAKES.md 📖 チートシート：references/SYNTAX_CHEATSHEET.md

---

httpbook UI 向けのフォーマット最適化

見やすく、把握しやすい構成

# ============================================================
# Article Endpoints - API Name
# ============================================================
# V1-Basic | V2-Metadata | V3-Full Content⭐
# Docs: https://api.example.com/docs
# ============================================================

@baseUrl = {{API_BASE_URL}}

### Get Articles V3 ⭐

# @name getArticlesV3
# @description Full content + Base64 HTML | Requires auth | Auto-decode
GET {{baseUrl}}/articles?page=1
Authorization: Bearer {{accessToken}}

フォーマットのガイドライン

推奨事項：

• ✅ 60 文字の区切りを使用：# =============
• ✅ | を使って説明をインラインで記述：Detail 1 | Detail 2
• ✅ ホバー時の詳細表示には @description を使用
• ✅ 視認性の目印に絵文字を使用：⭐⚠️📄

避ける事項：

• ❌ 80 文字以上の区切り
• ❌ HTML コメント ``（UI に表示されます）
• ❌ 複数行のドキュメントブロック
• ❌ ### による過剰な装飾

📖 ガイドの全容：変更前後の例については SKILL.md のフェーズ 3.5 を参照してください

---

セキュリティ設定

必須の .gitignore

# httpYac: Protect secrets
.env
.env.local
.env.*.local
.env.production

# httpYac: Ignore cache
.httpyac.cache
*.httpyac.cache
httpyac-output/

セキュリティルール

必ず行うこと：

• ✅ シークレットには環境変数を使用
• ✅ .gitignore に .env を追加
• ✅ 実際のシークレットを含まない .env.example を用意
• ✅ ログ内のトークンを切り詰める：token.substring(0, 10) + '...'

絶対に行わないこと：

• ❌ .http ファイルに認証情報をハードコード
• ❌ .env ファイルをコミット
• ❌ トークンやシークレットをすべてログに記録
• ❌ 本番環境で SSL を無効化

📖 ガイドの全容：references/SECURITY.md 検索パターン：grep -n "gitignore\|secrets" references/SECURITY.md

---

リファレンス資料の読み込みガイド

次の場合にリファレンスを読み込みます：

状況	読み込むファイル	grep 検索パターン
認証の設定	references/AUTHENTICATION_PATTERNS.md	grep -n "Pattern [0-9]"
スクリプト実行エラー	references/SCRIPTING_TESTING.md	grep -n "Pre-Request|Post-Response"
環境の切り替え	references/ENVIRONMENT_MANAGEMENT.md	grep -n "\.env|\.httpyac"
セキュリティ設定	references/SECURITY.md	grep -n "gitignore|secrets"
チーム向けドキュメント	references/DOCUMENTATION.md	grep -n "README|CHANGELOG"
高度な機能	references/ADVANCED_FEATURES.md	grep -n "GraphQL|WebSocket|gRPC"
CI/CD 統合	references/CLI_CICD.md	grep -n "GitHub Actions|GitLab"
構文リファレンスの全容	references/SYNTAX.md	grep -n "@|??|{{" references/SYNTAX.md

クイックリファレンス（いつでも利用可能）：

• references/SYNTAX_CHEATSHEET.md - よく使う構文パターン
• references/COMMON_MISTAKES.md - エラーの防止
• references/WORKFLOW_GUIDE.md - ワークフローの全容

---

ワークフローの全フェーズ

このスキルは 7 フェーズのワークフローに従います。フェーズ 1～3 は上記で説明しました。残りのフェーズは次のとおりです。

フェーズ 4：スクリプトとテスト

• リクエスト前後のスクリプト
• テストのアサーション
• リクエストの連鎖
• 📖 リファレンス：references/SCRIPTING_TESTING.md

フェーズ 5：環境管理

• 変数用の .env ファイル
• 設定用の .httpyac.json
• 複数環境のセットアップ
• 📖 リファレンス：references/ENVIRONMENT_MANAGEMENT.md

フェーズ 6：ドキュメント

• README.md の作成
• ファイル内のコメント
• API リファレンス
• 📖 リファレンス：references/DOCUMENTATION.md

フェーズ 7：CI/CD 統合（任意）

• GitHub Actions のセットアップ
• GitLab CI の設定
• Docker の統合
• 📖 リファレンス：references/CLI_CICD.md

---

品質チェックリスト

完了前に、次の項目を確認してください。

構造:

• コレクションの規模に適したファイル構造である
• テンプレートをベースとして使用している
• リクエストが ### で区切られている

構文:

• 変数: @var = {{ENV_VAR}}
• 関数が正しくエクスポートされ、呼び出されている
• 構文エラーがない（参照資料に照らして検証済み）

セキュリティ:

• .env が .gitignore に含まれている
• .env.example にプレースホルダーが記載されている
• 認証情報がハードコードされていない

機能:

• すべてのリクエストが正常に実行される
• 認証フローが動作する
• リクエストチェーンでデータが正しく渡される

ドキュメント:

• クイックスタートを含む README.md がある
• 環境変数が説明されている
• コメントが明確かつ簡潔である

---

よくある問題

症状	考えられる原因	解決方法
"Variable not defined"	@ を付けて宣言していない	先頭に @var = {{ENV_VAR}} を追加する
"Function not defined"	エクスポートされていない	exports.func = function() {} を使用する
スクリプトが実行されない	構文または位置が誤っている	{{ }} の配置を確認する
トークンが保持されない	ローカル変数を使用している	代わりに exports.token を使用する
環境が読み込まれない	ファイルの場所が誤っている	.env をプロジェクトのルートに配置する

📖 完全なトラブルシューティング: references/TROUBLESHOOTING.md

---

成功基準

次の条件を満たすと、コレクションは本番環境で使用できる状態です。

1. ✅ すべての .http ファイルがエラーなしで実行される
2. ✅ 認証フローが自動的に動作する
3. ✅ 環境の切り替え（dev/production）がテスト済みである
4. ✅ シークレットが保護されている（.env は gitignore 対象）
5. ✅ チームメンバーがクローンして 5 分以内に実行できる
6. ✅ リクエストにアサーションが含まれている
7. ✅ ドキュメントが完成している

---

実装上の注意

ファイルを生成する前:

• ユーザーと構造を確認する
• API ドキュメントが完全であることを検証する
• 認証要件を確認する

生成中:

• 常に assets/ のテンプレートを使用する
• 書き込む前に構文を検証する
• 必要に応じて認証を含める
• 重要なエンドポイントにアサーションを追加する

生成後:

• 作成した構造をユーザーに示す
• 少なくとも 1 つのリクエストをテストする
• 次の手順（認証情報、テスト）を明示する
• エンドポイントの追加を提案する

よくあるユーザーのリクエスト:

• "Add authentication" → references/AUTHENTICATION_PATTERNS.md を読み込む → パターンを選択する
• "Not working" → 変数の定義、{{ }} 構文、.env の読み込みを確認する
• "Chain requests" → # @name と exports 変数を使用する
• "Add tests" → アサーションを含む {{ }} ブロックを追加する
• "CI/CD setup" → references/CLI_CICD.md を読み込む → 例を提示する

---

バージョン

バージョン: 2.0.0 (Refactored) 最終更新日: 2025-12-15 ベース: httpYac v6.x

v1.x からの主な変更点:

• モジュール化された参照資料（7 ファイル）に再構成
• ワークフローのガイダンスと判断ポイントに重点を置く
• 段階的開示の設計（必要に応じて詳細を読み込む）
• 参照資料をすばやく確認できる grep パターン
• SKILL.md を 1289 行から約 400 行に削減

機能:

• テンプレートベースのファイル生成
• 10 種類の認証パターン
• 複数環境の管理
• セキュリティのベストプラクティス
• CI/CD 統合の例
• 高度な機能（GraphQL、WebSocket、gRPC）