StepZen VS Code Extension

A comprehensive VS Code extension for developing GraphQL APIs with StepZen, featuring intelligent schema management, import capabilities, and development tools.

Features

🚀 Import & Integration

• cURL Import - Convert REST endpoints to GraphQL with smart cURL parsing
• OpenAPI Import - Generate schemas from OpenAPI specifications
• GraphQL Import - Import existing GraphQL endpoints with authentication
• Database Import - Connect PostgreSQL, MySQL, Oracle, Snowflake, and more
• Smart Configuration - Auto-detect secrets, generate names, validate inputs

📊 Schema Management

• Schema Indexing - Real-time analysis of GraphQL schemas and directives
• Type Definitions - Navigate and explore your schema structure
• Directive Support - Full support for StepZen directives (@rest, @dbquery, @graphql, etc.)
• File Watching - Automatic updates when schema files change

🛠️ Development Tools

• CLI Integration - Seamless StepZen CLI command execution
• Project Management - Initialize and manage StepZen projects
• Request Testing - Execute GraphQL operations directly from VS Code
• Error Handling - Comprehensive error reporting and validation

🎯 Smart Features

• Auto-completion - Intelligent suggestions for StepZen directives
• Syntax Highlighting - Enhanced GraphQL syntax support
• Schema Validation - Real-time validation of schema files
• GraphQL Linting - Comprehensive GraphQL schema linting with custom rules
• Quick Actions - Context-aware commands and shortcuts

Quick Start

Installation

1. Install the extension from the VS Code Marketplace
2. Ensure you have the StepZen CLI installed
3. Open a workspace and start building GraphQL APIs

Import Your First API

Import a REST API

# Command Palette: "StepZen: Import cURL"
# Paste your cURL command or endpoint URL
curl -H "Authorization: Bearer token" https://api.github.com/user

Import a Database

# Command Palette: "StepZen: Import Database"
# Select database type and provide connection details
postgresql://user:pass@localhost:5432/mydb

Import GraphQL Endpoint

# Command Palette: "StepZen: Import GraphQL"
# Provide endpoint and authentication
https://api.github.com/graphql

Import OpenAPI Specification

# Command Palette: "StepZen: Import OpenAPI"
# Select local file or provide URL
https://petstore.swagger.io/v2/swagger.json

Commands

Import Commands

• StepZen: Import cURL - Import REST endpoints using cURL syntax
• StepZen: Import OpenAPI - Import from OpenAPI/Swagger specifications
• StepZen: Import GraphQL - Import existing GraphQL endpoints
• StepZen: Import Database - Import database schemas (PostgreSQL, MySQL, etc.)

Development Commands

• StepZen: Initialize Project - Create a new StepZen project
• StepZen: Deploy Schema - Deploy your schema to StepZen
• StepZen: Run GraphQL Request - Execute GraphQL operations
• StepZen: Open Schema Visualizer - Visualize your schema structure
• StepZen: Lint GraphQL Schema - Lint GraphQL schema files with custom rules

Utility Commands

• StepZen: Generate Operations - Create sample GraphQL operations
• StepZen: Validate Schema - Check schema for errors
• StepZen: Show Logs - View extension logs and debugging info

GraphQL Linting

The extension includes comprehensive GraphQL schema linting with custom rules:

Features

• Real-time Linting - Automatically lint GraphQL files as you type (optional)
• Comprehensive Rules - Built-in GraphQL best practices and StepZen-specific rules
• VS Code Integration - Linting errors and warnings appear in the Problems panel
• Customizable Rules - Configure linting rules through VS Code settings

Configuration

Enable automatic linting in your VS Code settings:

{
  "stepzen.autoLintGraphQL": true
}

Manual Linting

Use the command palette to manually lint your GraphQL schema:

1. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Run StepZen: Lint GraphQL Schema
3. View results in the Problems panel

Import Features

Smart cURL Parsing

• Auto-detection of authentication headers and secrets
• Path parameter extraction and configuration
• Query name generation from URL paths
• Schema naming from hostnames

Database Integration

• Multiple database types: PostgreSQL, MySQL, IBM Db2, Oracle, Snowflake, Presto
• Flexible connection: Connection strings or individual parameters
• Auto-linking: Automatic @materializer relationships
• Advanced options: Schema selection, table filtering, custom naming

Authentication Support

• Bearer tokens for API authentication
• API key headers with custom header names
• Basic authentication with username/password
• Custom headers for proprietary auth schemes
• Secret management with automatic detection and secure storage

Configuration Options

• Working directories for organized project structure
• Schema naming with validation and suggestions
• Type prefixes to avoid naming conflicts
• Advanced settings for fine-tuned control

Architecture

The extension follows a layered architecture with clear separation of concerns:

Extension Layer (Commands, Panels, Utils)
    ↓
Service Registry (CLI, Logger, Import, SchemaIndex, Request, GraphQLLinter)
    ↓
Schema Processing Layer (Indexer, Linker, Parser)
    ↓
Types (Pure data structures)

Key Services

• ImportService - Handles all import operations with type-specific builders
• SchemaIndexService - Real-time schema analysis and indexing
• GraphQLLinterService - GraphQL schema linting with graphql-eslint
• StepzenCliService - CLI integration and command execution
• Logger - Comprehensive logging and debugging
• RequestService - GraphQL request execution

Configuration

Extension Settings

{
  "stepzen.cliPath": "/path/to/stepzen",
  "stepzen.logLevel": "info",
  "stepzen.autoValidate": true,
  "stepzen.defaultWorkingDir": "./stepzen",
  "stepzen.autoLintGraphQL": false
}

Project Configuration

The extension automatically detects StepZen projects and provides context-aware features based on your stepzen.config.json and schema files.

Development

Prerequisites

• Node.js 16+
• VS Code 1.74+
• StepZen CLI

Building from Source

git clone https://github.com/stepzen-dev/vscode-stepzen
cd vscode-stepzen
npm install
npm run compile

Running Tests

npm test                    # Run all tests
npm run test:unit          # Unit tests only
npm run test:integration   # Integration tests only

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

Troubleshooting

Common Issues

CLI Not Found

• Ensure StepZen CLI is installed and in your PATH
• Set stepzen.cliPath in VS Code settings if needed

Import Failures

• Check network connectivity for remote resources
• Verify authentication credentials
• Review VS Code output panel for detailed error messages

Schema Validation Errors

• Ensure GraphQL syntax is correct
• Check StepZen directive usage
• Validate file paths and references

GraphQL Linting Issues

• Check that GraphQL files have valid syntax
• Verify VS Code settings are correct
• Review extension output for error messages

Getting Help

• Check the StepZen Documentation
• Review extension logs in VS Code Output panel
• Report issues on GitHub

License

This extension is licensed under the MIT License. See LICENSE for details.

---

Portions of the Content may be generated with the assistance of CursorAI