CursorToys: Command - generate-http-requests (2026-01-02)

.cursortoys-metadata.json

{
  "cursortoys": {
    "version": "1.2.0",
    "type": "command",
    "created": "2026-01-02T18:54:32.928Z",
    "fileCount": 1,
    "files": [
      {
        "name": "generate-http-requests.md",
        "type": "command",
        "size": 17886
      }
    ]
  }
}

generate-http-requests.md

description	tags
Analyzes ANY backend project, automatically identifies REST endpoints and generates .req files (curl) organized by resource/folders in .cursor/http, creating environments only when needed	documentation api http testing agnostic

Generate HTTP Documentation with cURL (Agnostic & Smart)

Overview

Analyzes the project identifying REST endpoints through multiple strategies (code annotations, OpenAPI specs, route files, etc.) and generates HTTP request files (.req) in curl format intelligently organized by folders/resources.

Expected Result:

• .cursor/http/ structure created with .req files organized (by folders if needed)
• .env file created ONLY if there are useful variables (BASE_URL always included)
• Simple requests WITHOUT # @env when not using variables
• Requests WITH # @env when using environment variables
• Organization by folders when there are clear logical groupings

Acceptance Criteria:

• All REST endpoints in the project are identified regardless of technology
• .req files follow the specified format
• Smart organization: single folder if few resources (<5), subfolders if many (≥5)
• .env created only with relevant variables identified in the project
• Requests use variables ONLY when it makes sense (URLs, identified tokens)
• Clean and pragmatic structure

Scope:

• REST endpoints (GET, POST, PUT, PATCH, DELETE)
• Multi-technology support:
  • Java: Spring Boot (@RestController, @RequestMapping, @GetMapping, etc.)
  • Python: FastAPI, Flask, Django (@app.route, @get, @post, etc.)
  • JavaScript/TypeScript: Express, NestJS, Fastify (app.get, @Get, etc.)
  • Go: Gin, Echo, Chi (router.GET, e.GET, etc.)
  • Specifications: OpenAPI/Swagger (openapi.yaml, swagger.json)
  • Route files: routes.js, urls.py, routes.rb, etc.

Limitations:

• Does not include messaging/websocket endpoints
• Does not include internal endpoints (health checks, metrics)
• Example tokens (not real tokens)
• Payloads are generic examples when no schema is available

Steps

1. Identify Technology and Project Structure

   • Look for configuration files:
     • Java: pom.xml, build.gradle → Spring Boot
     • Python: requirements.txt, pyproject.toml → FastAPI/Flask/Django
     • JavaScript/TypeScript: package.json → Express/NestJS/Fastify
     • Go: go.mod → Gin/Echo/Chi
     • Ruby: Gemfile → Rails/Sinatra
   • Identify structure patterns:
     • Controllers/Routes
     • OpenAPI specifications
     • Typical directories (src/, app/, api/, routes/)

2. Search for Endpoints Using Multiple Strategies

   Strategy 1: OpenAPI/Swagger Specifications

   • Search for: openapi.yaml, openapi.json, swagger.yaml, swagger.json
   • Typical locations: src/main/resources/, docs/, api/, project root
   • Extract: paths, methods, parameters, schemas, securitySchemes

   Strategy 2: Code Annotations (Java/Spring)

   • Search for classes: @RestController, @Controller
   • Search for methods: @GetMapping, @PostMapping, @PutMapping, @DeleteMapping, @RequestMapping
   • Extract: path, HTTP method, @PathVariable, @RequestParam, @RequestBody

   Strategy 3: Python Decorators (FastAPI/Flask)

   • Search for: @app.route, @router.get, @router.post, @app.get, @app.post
   • Files: main.py, app.py, routes.py, api.py, **/routers/*.py
   • Extract: path, method, function parameters, type hints

   Strategy 4: JavaScript/TypeScript Routes

   • Search for: app.get(, app.post(, router.get(, @Get(, @Post(
   • Files: routes.js, routes.ts, *.controller.ts, server.js
   • Extract: path, method, middleware

   Strategy 5: Go Routes

   • Search for: router.GET(, e.GET(, r.Get(, Handle(, HandleFunc(
   • Files: routes.go, main.go, handlers.go, *_handler.go
   • Extract: path, method, handler

   Strategy 6: Dedicated Route Files

   • Search for: routes.rb, urls.py, routes.php, web.php
   • Parse technology-specific structure

3. Consolidate and Organize Found Endpoints

   • Group endpoints by resource/module:
     • By path prefix: /api/users/* → users
     • By controller/class: UserController → users
     • By OpenAPI tag: tag "users" → users
   • Data structure for each endpoint:

     {
       resource: "users",
       method: "GET",
       path: "/api/users/{id}",
       queryParams: ["include"],
       pathParams: ["id"],
       requestBody: {...schema...},
       description: "Get user by ID",
       headers: ["Authorization"],
       requiresAuth: true
     }
     

   • Identify logical groupings:
     • If ≥ 5 resources: consider subfolders by module/domain
     • If < 5 resources: keep flat structure

4. Detect Project Configurations and Variables

   Detect BASE_URL:

   • Application port:
     • Java: application.properties, application.yml → server.port
     • Python: .env, code → PORT, HOST
     • JS/TS: package.json, .env → PORT
     • Go: main code → Listen(:
     • Defaults: 8080 (Java), 5000 (Python), 3000 (JS), 8000 (Go)
   • Context path/base path:
     • Java Spring: server.servlet.context-path
     • OpenAPI: servers[].url
     • Common prefixes: /api, /v1, /api/v1

   Detect Need for Other Variables:

   • Search for authentication:
     • OpenAPI: securitySchemes (Bearer, Basic, ApiKey)
     • Code: Authorization headers, auth middleware
     • If found: create AUTH_TOKEN variable
   • Search for API Keys:
     • Headers: X-API-Key, api-key, apikey
     • Query params: apiKey, api_key
     • If found: create API_KEY variable
   • Search for tokens/secrets:
     • Environment variables in code
     • .env.example files
     • If patterns found: include in .env

   Decision: Create .env or Not?

   • ALWAYS create: BASE_URL is always useful (even if it's the only one)
   • Content: Always have at least BASE_URL

5. Decide Organization Structure

   Scenario 1: Few Resources (< 5)

   .cursor/http/
   ├── .environments/
   │   └── .env
   ├── users.req
   ├── products.req
   └── orders.req
   

   Scenario 2: Many Resources (≥ 5)

   • Identify logical groupings:
     • By module: auth, admin, public
     • By domain: users, products, payments, notifications
     • By version: v1, v2

   .cursor/http/
   ├── .environments/
   │   └── .env
   ├── auth/
   │   ├── login.req
   │   └── tokens.req
   ├── users/
   │   ├── management.req
   │   └── profile.req
   └── products/
       ├── catalog.req
       └── inventory.req
   

   Scenario 3: Hybrid Structure

   • Main resources at root
   • Complex modules in subfolders

   .cursor/http/
   ├── .environments/
   │   └── .env
   ├── health.req
   ├── admin/
   │   ├── users.req
   │   └── settings.req
   └── api/
       ├── products.req
       └── orders.req
   

6. Generate Environment File

   • Create .cursor/http/.environments/.env:

     # {Project Name} Environment
     BASE_URL=http://localhost:{port}{context_path}

   • Add variables ONLY if identified:

     # Authentication (if found)
     AUTH_TOKEN=Bearer eyJ... # or Basic xxx
     
     # API Key (if found)
     API_KEY=your-api-key-here
     
     # Other specific identified variables

   • Don't invent unnecessary variables

7. Generate .req Files Intelligently

   Format WITH Variables (recommended - using block comments):

   /*
    * GET /users
    * Lista todos os usuários
    * 
    * Headers obrigatórios:
    * - Content-Type: application/json
    * 
    * Response: 200 OK
    */
   
   ## Get All Users
   curl --request GET \
     --url {{BASE_URL}}/users \
     --header 'Content-Type: application/json'
   
   /*
    * GET /users/{id}
    * Obtém um usuário por ID
    * Requer autenticação via Bearer token
    * 
    * Response: 200 OK
    */
   
   ## Get User by ID
   curl --request GET \
     --url {{BASE_URL}}/users/123 \
     --header 'Authorization: {{AUTH_TOKEN}}'

   Format WITHOUT Variables (simple request):

   /*
    * GET /api/users
    * Lista todos os usuários (sem variáveis de ambiente)
    */
   
   ## Get All Users
   curl --request GET \
     --url http://localhost:8080/api/users \
     --header 'Content-Type: application/json'

   Comment Format Rules:

   • Use block comments (/* ... */) for section documentation
   • Block comments should include:
     • HTTP method and path
     • Brief description
     • Required/optional headers
     • Query params (if applicable)
     • Expected response code
     • Any important notes
   • Use ## Request Name before each curl command
   • Use # @env dev ONLY at the top of file (global environment)

   Variable Usage Rules:

   • Use {{BASE_URL}} if .env was created
   • Use {{AUTH_TOKEN}} if authentication was identified
   • Use {{API_KEY}} if API key was identified
   • DON'T use variables if they weren't defined in .env
   • Single # @env dev at file top applies to all requests

8. Generate .req File Contents

   File Header Structure:

   • Start with comprehensive block comment describing the entire file:

   /*
    * RESOURCE NAME - Brief Description
    * 
    * Complete description of what this file contains
    * Total de endpoints: X (Y variações de requests)
    * 
    * Environment: qa (aplicado globalmente)
    * Base URL: {{BASE_URL}}
    * 
    * Recursos:
    * 1. First feature/endpoint group
    * 2. Second feature/endpoint group
    * 3. Third feature/endpoint group
    */
   
   # @env qa

   • For each resource/file:
     • File header block comment (as above)
     • Section block comments for each endpoint group
     • Requests ordered logically:
       1. GET (list)
       2. GET (get by ID)
       3. POST (create)
       4. PUT/PATCH (update)
       5. DELETE (remove)

   Section Block Comment Structure:

   /*
    * ========================================
    * SECTION NUMBER. SECTION NAME
    * ========================================
    * 
    * HTTP_METHOD /path/to/endpoint
    * Brief description of what this endpoint does
    * 
    * Headers obrigatórios:
    * - Header-Name: Description
    * 
    * Headers opcionais:
    * - Optional-Header: Description
    * 
    * Query params opcionais:
    * - param1: Description
    * - param2: Description
    * 
    * Response: 200 OK
    * {
    *   "example": "response structure if relevant"
    * }
    */
   
   ## Request Name
   curl --request METHOD \
     --url {{BASE_URL}}/path \
     --header 'Header: Value'

   Replace Path Parameters:

   • {id} → plausible number (123, 1034)
   • {uuid} → example UUID
   • {name}, {slug} → kebab-case-string
   • {status} → identified enum value (ACTIVE, PENDING)

   Add Query Parameters:

   • Include when identified
   • Use realistic example values
   • Document in block comment (optional vs required)

   Generate JSON Payloads:

   • If OpenAPI schema exists: use to generate example
   • If no schema: generate generic structure based on method
   • Use realistic values and correct types

9. Add Documentation and Context

   File Header (required at top of each .req file):

   /*
    * {RESOURCE NAME} - {Brief Title}
    * 
    * {Complete description of what this resource/file contains}
    * Total de endpoints: {count} ({variations} variações de requests)
    * 
    * Environment: qa (aplicado globalmente)
    * Base URL: {{BASE_URL}}
    * 
    * Recursos:
    * 1. {Feature 1}
    * 2. {Feature 2}
    * 3. {Feature 3}
    */
   
   # @env qa

   For each endpoint section:

   /*
    * ========================================
    * {NUMBER}. {SECTION NAME IN CAPS}
    * ========================================
    * 
    * {METHOD} {/path/to/endpoint}
    * {Brief description of what this endpoint does}
    * 
    * Headers obrigatórios:
    * - {Header-Name}: {Description/example}
    * 
    * Headers opcionais:
    * - {Header-Name}: {Description/example}
    * 
    * Query params opcionais:
    * - {param}: {Description with possible values}
    * - {param}: {Description}
    * 
    * {Important notes or observations}
    * 
    * Response: {200 OK}
    * {
    *   "example": "response if relevant"
    * }
    */
   
   ## {Request Name}
   curl --request {METHOD} \
     --url {{BASE_URL}}{/path} \
     --header 'Content-Type: application/json' \
     --header 'Authorization: {{AUTH_TOKEN}}' \
     --data '{
       "field": "value"
     }'

   For variations of same endpoint:

   /*
    * {Variation Name/Description}
    * {What makes this variation different}
    * {Useful notes about this specific case}
    */
   
   ## {Request Name - Variation}
   curl --request {METHOD} \
     --url {{BASE_URL}}{/path}?{params} \
     --header 'Authorization: {{AUTH_TOKEN}}'

   Best Practices:

   • Use block comments (/* ... */) for all documentation
   • Keep block comments clear and structured
   • Include method and path in section headers
   • Document all headers (required vs optional)
   • List query parameters with descriptions
   • Add response examples when relevant
   • Note authentication requirements
   • Highlight important behaviors or edge cases

10. Create README.md Documentation

    • Create .cursor/http/README.md:

      # HTTP Requests - {Project Name}
      
      ## 📁 Structure
      {List created folder/file structure}
      
      ## 🚀 How to Use
      1. Copy the desired curl command
      2. Execute in terminal
      3. For requests with variables: make sure you have `.env` configured
      
      ## 🔧 Environments
      {If .env exists}
      - Edit `.environments/.env` with your values
      - Available variables:
        - `BASE_URL`: API base URL
        - `AUTH_TOKEN`: Authentication token (if applicable)
        - `API_KEY`: API key (if applicable)
      
      {If .env does NOT exist}
      - Requests use direct URLs (no variables)
      - Edit curls as needed
      
      ## 📊 Statistics
      - Total endpoints: {count}
      - Resources: {count}
      - Detected technology: {tech}
      
      ## 📚 Available Resources
      {List each .req file with brief description}

11. Validate and Finalize

    • Verify syntax of all .req files:
      • Single # @env {env} at top of file (global environment)
      • Block comments (/* ... */) for all documentation
      • File header block comment with complete overview
      • Section block comments for each endpoint group
      • Variables in {{VAR}} format
      • Line continuation with \
      • Valid JSON in --data
      • Correct headers
    • Verify .env contains only actually used variables
    • Verify folder structure makes sense
    • List final structure created for user:

      ✅ Structure created in .cursor/http/
      
      📁 .cursor/http/
      ├── .environments/
      │   └── .env (BASE_URL + 2 other variables)
      ├── auth/
      │   ├── login.req (3 endpoints)
      │   └── tokens.req (2 endpoints)
      ├── users.req (8 endpoints)
      └── products.req (6 endpoints)
      
      📊 Total: 19 mapped endpoints
      🔧 Technology: Spring Boot
      ✨ Organization: By module (auth in folder, others at root)
      ✨ Documentation: Block comments format with complete context
      

Verification Checklist

• Project was analyzed and technology identified
• Endpoints were found by at least one strategy
• .cursor/http/ structure was created
• Decision to create/not create subfolders was made based on number of resources
• .env file was created WITH BASE_URL (always)
• .env file contains ONLY variables identified in project (not invented)
• .req files were created organized (by folder if ≥5 resources)
• Single # @env {env} at top of each file (global environment)
• All variables used in .req exist in .env
• File header block comment created for each .req file
• Section block comments created for each endpoint group
• Block comments include method, path, headers, params, response info
• Block comments (/* ... */) used instead of ### comments
• Path parameters were replaced with example values
• Query parameters were included when identified
• Necessary headers are present
• POST/PUT/PATCH requests include --data when applicable
• JSON payloads are valid (when included)
• Descriptions were extracted when available
• Requests are logically ordered (GET → POST → PUT → DELETE)
• curl format is correct (line continuation with \)
• BASE_URL is correct (detected port + context path)
• README.md was created in .cursor/http/
• Final structure was clearly listed to user
• Total endpoints and technology were informed
• Organization structure is clean and pragmatic
• Documentation format follows block comments standard

Troubleshooting

If no endpoints are found:

• List tried strategies and checked files
• Suggest manual search in specific directories
• Offer to create basic example structure

If port/context path not detected:

• Use technology-based defaults
• Inform user they need to adjust BASE_URL

If too many endpoints (>50):

• Mandatory use of subfolder structure
• Group more granularly (by module/domain)
• Create index in README.md

If no variables identified beyond BASE_URL:

• Create .env only with BASE_URL
• Use simple requests (without # @env) when possible
• Inform user they can add variables manually if needed