feat(gin): Add comprehensive Gin framework support

.github/workflows/ci.yml

@@ -34,11 +34,11 @@ jobs:
         run: git diff --exit-code -- go.mod go.sum
 
       - name: Setup golangci-lint
-        uses: golangci/golangci-lint-action@v7
+        uses: golangci/golangci-lint-action@v9
         with:
-          version: v2.10
-          args: --help
-          verify: false
+          version: latest
+          verify: true
+          install-only: true
 
       - name: Format check
         run: make fmt

.gitignore

@@ -66,3 +66,5 @@ output/
 integration-tests/gozero-demo/openapi.yaml
 integration-tests/gozero-demo/openapi.json
 
+integration-tests/gin-demo/openapi.yaml
+/openapi/openapi.yaml

.golangci.yml

@@ -131,8 +131,6 @@ linters:
           msg: use log/slog for logging
         - pattern: fmt\.Fprint(os\.(Stdout|Stderr),.*)$
           msg: use log/slog for logging
-      # Exclude test files from this check
-      exclude_godoc_examples: true
 
   exclusions:
     generated: lax
@@ -179,7 +177,8 @@ formatters:
       extra-rules: true
 
     goimports:
-      local-prefixes: github.com/spencercjh/spec-forge
+      local-prefixes:
+        - github.com/spencercjh/spec-forge
 
   exclusions:
     generated: lax

CLAUDE.md

@@ -50,22 +50,28 @@ internal/
 ├── executor/             # Shell command execution with timeout
 ├── extractor/            # OpenAPI spec extraction
 │   ├── types.go          # GenerateOptions, GenerateResult, etc.
-│   ├── builtin/          # Built-in extractor registry
-│   ├── spring/           # Spring Boot implementation
+│   ├── spring/           # Spring Boot specific implementation
 │   │   ├── detector.go   # Project type detection (Maven/Gradle)
 │   │   ├── patcher.go    # springdoc dependency injection
 │   │   ├── generator.go  # Maven/Gradle command execution
 │   │   ├── maven.go      # POM parsing, spring-boot plugin config
 │   │   └── gradle.go     # build.gradle parsing
-│   ├── gozero/           # go-zero implementation
+│   ├── gozero/           # go-zero framework support
 │   │   ├── detector.go   # go.mod parsing, dependency detection
 │   │   ├── patcher.go    # go-swagger installation check
 │   │   └── generator.go  # goctl command execution
-│   └── grpcprotoc/       # gRPC-protoc implementation
-│       ├── detector.go   # .proto file detection, buf.yaml rejection
-│       ├── patcher.go    # protoc tools check
-│       ├── generator.go  # protoc command execution
-│       └── grpcprotoc.go # Info struct with ProtoFiles, ServiceProtoFiles
+│   ├── grpcprotoc/       # gRPC-protoc implementation
+│   │   ├── detector.go   # .proto file detection, buf.yaml rejection
+│   │   ├── patcher.go    # protoc tools check
+│   │   ├── generator.go  # protoc command execution
+│   │   └── grpcprotoc.go # Info struct with ProtoFiles, ServiceProtoFiles
+│   └── gin/              # Gin framework support (AST-based)
+│       ├── detector.go   # go.mod parsing for gin dependency
+│       ├── patcher.go    # No-op (no patching needed)
+│       ├── generator.go  # AST-based OpenAPI generation
+│       ├── ast_parser.go # Go AST parsing for routes
+│       ├── handler_analyzer.go # Handler function analysis
+│       └── schema_extractor.go # Go struct to OpenAPI schema
 ├── validator/            # kin-openapi validation
 ├── enricher/             # LLM-based description enrichment
 │   ├── enricher.go       # Main enricher interface
@@ -84,6 +90,7 @@ internal/
 
 ```
 Spring Project → springdoc plugin → openapi.json → Enricher (LLM) → openapi.yaml
+Gin Project → AST Parser → OpenAPI Generator → Enricher (LLM) → openapi.yaml
 ```
 
 ## Critical Constraints
@@ -168,7 +175,7 @@ API keys should be provided via environment variables:
 
 ## Functional Testing with Example Projects
 
-The `integration-tests/` directory contains example Spring Boot projects for testing:
+The `integration-tests/` directory contains example projects for testing:
 
 ```
 integration-tests/
@@ -177,7 +184,41 @@ integration-tests/
 ├── maven-springboot-openapi-demo/     # Maven-based Spring Boot project
 ├── gradle-springboot-openapi-demo/    # Gradle-based Spring Boot project
 ├── maven-multi-module-demo/           # Multi-module Maven project
-└── gradle-multi-module-demo/          # Multi-module Gradle project
+├── gradle-multi-module-demo/          # Multi-module Gradle project
+└── gin-demo/                          # Gin framework project
+```
+
+### Gin Framework Development
+
+The Gin extractor is located in `internal/extractor/gin/`.
+
+**Architecture:**
+- Uses Go AST (go/ast, go/parser) for static analysis
+- No runtime execution required (unlike Spring Boot)
+- Patcher is a no-op (no dependencies to install)
+
+**Key Components:**
+- `ASTParser` - Parses Go files and extracts routes
+- `HandlerAnalyzer` - Analyzes handler functions for params/responses
+- `SchemaExtractor` - Converts Go structs to OpenAPI schemas
+
+**Testing:**
+```bash
+# Run Gin-specific tests
+go test -v ./internal/extractor/gin/...
+
+# Run Gin e2e test (requires go.mod with gin dependency)
+go test -v -tags=e2e ./integration-tests/... -run TestGinDemo
+```
+
+**Example Usage:**
+```bash
+# Generate OpenAPI spec from a Gin project
+spec-forge generate ./integration-tests/gin-demo
+
+# Generate with AI enrichment
+LLM_API_KEY="your-key" spec-forge generate ./integration-tests/gin-demo \
+    --enrich --language zh
 ```
 
 ### Running E2E Tests

README.md

@@ -93,11 +93,41 @@ LLM_API_KEY="sk-xxx" spec-forge enrich ./openapi.json \
     --model deepseek-chat
 ```
 
+### Framework-Specific Usage
+
+#### Gin Framework
+
+For Gin projects, spec-forge uses static AST analysis (no runtime required):
+
+```bash
+# Basic generation from a Gin project
+cd my-gin-project
+spec-forge generate . -o ./openapi
+
+# Generate with AI enrichment
+LLM_API_KEY="sk-xxx" spec-forge generate . \
+    --enrich \
+    --provider custom \
+    --model deepseek-chat \
+    --language zh
+
+# Verbose mode to see extraction details
+spec-forge generate . -v
+```
+
+Supported Gin patterns:
+- Direct route registration: `r.GET("/users", handler)`
+- Route groups: `api := r.Group("/api")`
+- Middleware chains: `r.Use(auth).GET("/protected", handler)`
+- Parameter binding: `c.Param()`, `c.Query()`, `c.ShouldBindJSON()`
+- Response types: extracted from `c.JSON()` calls with type inference
+
 ## Supported Frameworks
 
 | Framework                                                                                                                                    | Language       | Status         |
 |----------------------------------------------------------------------------------------------------------------------------------------------|----------------|----------------|
 | [Spring Boot](https://springdoc.org/#plugins)                                                                                                | Java           | ✅ Supported    |
+| [Gin](https://gin-gonic.com/)                                                                                                                | Go             | ✅ Supported    |
 | [go-zero](https://go-zero.dev/reference/cli-guide/swagger/)                                                                                  | Go             | ✅ Supported    |
 | [gRPC (protoc)](https://github.com/sudorandom/protoc-gen-connect-openapi)                                                                    | Multi-language | ✅ Supported    |
 | [Hertz](https://github.com/hertz-contrib/swagger-generate/tree/main/protoc-gen-http-swagger)                                                 | Go             | 🚧 Coming soon |

cmd/generate.go

@@ -230,12 +230,17 @@ func runGenerate(cmd *cobra.Command, args []string) error { //nolint:gocyclo //
 			slog.InfoContext(ctx, "Publisher output", "message", pubResult.Message)
 		}
 	} else if outputDir != "" {
-		// Skip publish: just copy to output directory
-		if err := copySpecToOutput(genResult.SpecFilePath, outputDir); err != nil {
-			return errWrap("failed to copy spec to output directory", err)
+		// Skip publish: just copy to output directory if needed
+		genDir := filepath.Dir(genResult.SpecFilePath)
+		if genDir != outputDir {
+			if err := copySpecToOutput(genResult.SpecFilePath, outputDir); err != nil {
+				return errWrap("failed to copy spec to output directory", err)
+			}
+			finalSpecPath := filepath.Join(outputDir, filepath.Base(genResult.SpecFilePath))
+			slog.InfoContext(ctx, "Spec copied to output directory (publish skipped)", "path", finalSpecPath)
+		} else {
+			slog.InfoContext(ctx, "Spec already in output directory", "path", genResult.SpecFilePath)
 		}
-		finalSpecPath := filepath.Join(outputDir, filepath.Base(genResult.SpecFilePath))
-		slog.InfoContext(ctx, "Spec copied to output directory (publish skipped)", "path", finalSpecPath)
 	}
 
 	// Step 8: Output final result