spencercjh · spencercjh · Mar 8, 2026 · Mar 8, 2026 · Mar 8, 2026 · Mar 8, 2026
diff --git a/README.md b/README.md
@@ -6,14 +6,65 @@
 [![Copilot code review](https://github.com/spencercjh/spec-forge/actions/workflows/copilot-pull-request-reviewer/copilot-pull-request-reviewer/badge.svg)](https://github.com/spencercjh/spec-forge/actions/workflows/copilot-pull-request-reviewer/copilot-pull-request-reviewer)
 [![Dependabot Updates](https://github.com/spencercjh/spec-forge/actions/workflows/dependabot/dependabot-updates/badge.svg)](https://github.com/spencercjh/spec-forge/actions/workflows/dependabot/dependabot-updates)
 
-A CLI tool that generates enriched OpenAPI specifications from source code using AI.
+A CLI tool that solves the fragmented, painful world of OpenAPI spec generation — auto-detects your framework, generates accurate specs from source code, and enriches them with AI.
+
+## Why spec-forge?
+
+Generating OpenAPI specs from backend code is harder than it should be. Every ecosystem has its own broken or half-working toolchain:
+
+### gRPC / Protobuf
+
+The tooling landscape is fragmented and poorly documented:
+
+- **`google/gnostic` (`protoc-gen-openapi`)** — inactive/unmaintained, yet still the top result in most tutorials
+- **`grpc-gateway`'s `protoc-gen-openapiv2`** — only outputs Swagger 2.0, not OpenAPI 3.x
+- **`buf`** — no official documentation for OpenAPI generation; developers rely entirely on third-party blog posts
+
+Developers waste hours just figuring out which tool to use before writing a single line of code. spec-forge wraps [`protoc-gen-connect-openapi`](https://github.com/sudorandom/protoc-gen-connect-openapi) — a maintained, OpenAPI 3.x-native solution — behind a single command.
+
+### Gin
+
+The dominant solution ([`swaggo/swag`](https://github.com/swaggo/swag)) requires hundreds of verbose annotations:
+
+```go
+// @Summary  Get user by ID
+// @Param    id   path  int  true  "User ID"
+// @Success  200  {object}  User
+// @Router   /users/{id} [get]
+func GetUser(c *gin.Context) { ... }
+```
+
+These annotations are **not validated by the Go compiler** — typos and stale references only surface at generation time. Renaming a type means manually updating annotations everywhere.
+
+**spec-forge requires zero annotations.** It uses Go AST analysis to read your routes, handler signatures, and struct definitions directly from source.
+
+### Hertz / Kitex (CloudWeGo)
+
+The official CloudWeGo documentation for OpenAPI generation is outdated. The recommended tools are in [`hertz-contrib/swagger-generate`](https://github.com/hertz-contrib/swagger-generate) — specifically `protoc-gen-http-swagger` for Hertz and `protoc-gen-rpc-swagger` for Kitex. spec-forge aims to wrap this complexity into a single command (support coming soon).
+
+### go-zero
+
+Support for go-zero projects is available. spec-forge uses `goctl api swagger` command to generate OpenAPI specs from `.api` definition files.
+
+---
+
+### What about just asking an LLM to write the docs?
+
+That's AI-generated docs — not the same thing.
+
+spec-forge reads your **actual code structure** to guarantee accuracy, then uses AI to fill in human-readable descriptions. The result is both machine-accurate and human-readable. Docs written from scratch by an LLM drift from reality the moment your code changes.
+
+### The AI Agent angle
+
+In the AI Agent era, OpenAPI specs are becoming machine-readable interface contracts. Agents use them to discover and call your APIs. spec-forge helps ensure yours are accurate, complete, and always in sync with your code.
 
 ## Features
 
 - 🔍 **Auto-detection** - Automatically detects project type and build tools
 - 🔧 **Auto-patching** - Adds required dependencies and plugins if missing
 - 🤖 **AI Enrichment** - Uses LLM to generate meaningful descriptions for APIs and schemas
 - 🌐 **Multi-provider** - Supports OpenAI, Anthropic, Ollama, and custom providers
+- ✍️ **Zero annotations for Gin** - AST-based analysis requires no `// @swagger` comments
 
 ## How It Works
 
@@ -46,15 +97,45 @@ go install github.com/spencercjh/spec-forge@latest
 # Generate OpenAPI spec from a Spring Boot project
 spec-forge generate ./path/to/spring-boot-project
 
-# Generate with AI enrichment
-LLM_API_KEY="your-api-key" spec-forge generate ./path/to/spring-boot-project \
-    --enrich --provider openai --model gpt-4o --language en
+# Generate from a Gin project (no annotations needed — pure AST analysis)
+spec-forge generate ./path/to/gin-project
+
+# Generate from a gRPC/protoc project
+spec-forge generate ./path/to/grpc-project
+
+# Generate from a go-zero project
+spec-forge generate ./path/to/go-zero-project
+
+# Generate with AI enrichment (configure .spec-forge.yaml first)
+spec-forge generate ./path/to/project --language zh
 
 # Enrich an existing OpenAPI spec
-LLM_API_KEY="your-api-key" spec-forge enrich ./openapi.json \
+OPENAI_API_KEY="your-api-key" spec-forge enrich ./openapi.json \
     --provider openai --model gpt-4o --language zh
 ```
 
+## Supported Frameworks
+
+| Framework                                                                                                                | Language       | Status         | Details                                     |
+|--------------------------------------------------------------------------------------------------------------------------|----------------|----------------|---------------------------------------------|
+| [Spring Boot](https://springdoc.org/#plugins)                                                                           | Java           | ✅ Supported   | [docs](./docs/spring-boot.md)               |
+| [Gin](https://gin-gonic.com/)                                                                                           | Go             | ✅ Supported   | [docs](./docs/gin.md)                       |
+| [go-zero](https://go-zero.dev/)                                                                                         | Go             | ✅ Supported   | [docs](./docs/go-zero.md)                   |
+| [gRPC (protoc)](https://github.com/sudorandom/protoc-gen-connect-openapi)                                               | Multi-language | ✅ Supported   | [docs](./docs/grpc-protoc.md)               |
+| [Hertz](https://github.com/cloudwego/hertz)                                                                             | Go             | 🚧 Coming soon | [docs](./docs/hertz.md)                     |
+| [Kitex](https://github.com/cloudwego/kitex)                                                                             | Go             | 🚧 Coming soon | [docs](./docs/kitex.md)                     |
+
+## Framework-Specific Usage
+
+See the detailed documentation for each framework:
+
+- [Spring Boot](./docs/spring-boot.md)
+- [Gin](./docs/gin.md) — Zero annotations required, AST-based analysis
+- [go-zero](./docs/go-zero.md)
+- [gRPC (protoc)](./docs/grpc-protoc.md) — Native protoc with `protoc-gen-connect-openapi`
+- [Hertz](./docs/hertz.md) — Coming soon
+- [Kitex](./docs/kitex.md) — Coming soon
+
 ## Configuration
 
 Create `.spec-forge.yaml` in your project root:
@@ -93,70 +174,6 @@ 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 |
-| [Kitex](https://github.com/hertz-contrib/swagger-generate/tree/main/protoc-gen-rpc-swagger)                                                  | Go             | 🚧 Coming soon |
-
-### gRPC Projects (Native protoc)
-
-For gRPC projects using native protoc (not buf-managed):
-
-```bash
-# Generate OpenAPI spec from proto files
-spec-forge generate ./my-grpc-project
-
-# With additional import paths
-spec-forge generate ./my-grpc-project --proto-import-path ./third_party --proto-import-path ./vendor
-
-# Generate with AI enrichment
-LLM_API_KEY="your-key" spec-forge generate ./my-grpc-project --enrich --language zh
-```
-
-**Requirements:**
-- `protoc` installed ([install guide](https://github.com/protocolbuffers/protobuf/releases))
-- `protoc-gen-connect-openapi` installed:
-  ```bash
-  go install github.com/sudorandom/protoc-gen-connect-openapi@latest
-  ```
-
-**Note:** buf-managed projects are not supported in this mode. Use `buf generate` with the plugin, then use `spec-forge enrich` on the generated OpenAPI spec.
-
 ## Supported Publishers
 
 | Publisher                         | Status         |
@@ -177,6 +194,7 @@ README_API_KEY="rdme_xxx" spec-forge publish ./openapi.json --to readme --readme
 
 # Or with full generate pipeline
 README_API_KEY="rdme_xxx" spec-forge generate ./my-project --publish-target readme
+```
 
 ## License
 

diff --git a/docs/gin.md b/docs/gin.md
@@ -0,0 +1,51 @@
+# Gin Framework
+
+Spec Forge uses **AST-based static analysis** to extract OpenAPI specs from Gin projects — **zero annotations required**.
+
+## Why Not `swaggo/swag`?
+
+The dominant solution ([`swaggo/swag`](https://github.com/swaggo/swag)) requires hundreds of verbose annotations:
+
+```go
+// @Summary  Get user by ID
+// @Param    id   path  int  true  "User ID"
+// @Success  200  {object}  User
+// @Router   /users/{id} [get]
+func GetUser(c *gin.Context) { ... }
+```
+
+These annotations are **not validated by the Go compiler** — typos and stale references only surface at generation time. Renaming a type means manually updating annotations everywhere.
+
+**Spec Forge requires zero annotations.** It uses Go AST analysis to read your routes, handler signatures, and struct definitions directly from source.
+
+## How It Works
+
+1. **Detection**: Parses `go.mod` to detect Gin dependency
+2. **Patching**: No-op (no dependencies to install)
+3. **Generation**: Uses Go AST parser to extract routes, handlers, and types
+
+## Supported 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
+
+## Usage
+
+```bash
+# Basic generation
+cd my-gin-project
+spec-forge generate . -o ./openapi
+
+# Generate with AI enrichment (configure .spec-forge.yaml first)
+spec-forge generate . --language zh
+
+# Verbose mode to see extraction details
+spec-forge generate . -v
+```
+
+## References
+
+- [Gin Web Framework](https://gin-gonic.com/)
diff --git a/docs/go-zero.md b/docs/go-zero.md
@@ -0,0 +1,32 @@
+# go-zero
+
+Spec Forge supports generating OpenAPI specs from [go-zero](https://go-zero.dev/) projects.
+
+## How It Works
+
+1. **Detection**: Parses `go.mod` to detect go-zero dependency and locate API definition files (`.api` files)
+2. **Patching**: Checks for `goctl` installation
+3. **Generation**: Uses `goctl api swagger` command to generate the OpenAPI spec
+
+## Prerequisites
+
+The `goctl` tool must be installed:
+
+```bash
+go install github.com/zeromicro/go-zero/tools/goctl@latest
+```
+
+## Usage
+
+```bash
+# Basic generation
+spec-forge generate ./my-go-zero-project
+
+# With AI enrichment
+spec-forge generate ./my-go-zero-project --language zh
+```
+
+## References
+
+- [go-zero Documentation](https://go-zero.dev/)
+- [go-zero Swagger CLI Reference](https://go-zero.dev/reference/cli-guide/swagger)
diff --git a/docs/grpc-protoc.md b/docs/grpc-protoc.md
@@ -0,0 +1,51 @@
+# gRPC / Protobuf (Native protoc)
+
+Spec Forge generates OpenAPI specs from `.proto` files using native `protoc` with the `protoc-gen-connect-openapi` plugin.
+
+## Why Not Other Tools?
+
+The gRPC OpenAPI tooling landscape is fragmented:
+
+| Tool | Status | Limitation |
+|------|--------|------------|
+| `google/gnostic` (`protoc-gen-openapi`) | Inactive/unmaintained | No recent updates |
+| `grpc-gateway`'s `protoc-gen-openapiv2` | Active | Only outputs Swagger 2.0, not OpenAPI 3.x |
+| `buf` | Active | No official documentation for OpenAPI generation; developers rely on third-party blog posts |
+
+**Spec Forge wraps [`protoc-gen-connect-openapi`](https://github.com/sudorandom/protoc-gen-connect-openapi)** — a maintained, OpenAPI 3.x-native solution.
+
+## How It Works
+
+1. **Detection**: Scans for `.proto` files (excludes `buf`-managed projects)
+2. **Patching**: Verifies `protoc` and `protoc-gen-connect-openapi` are installed
+3. **Generation**: Runs `protoc` with the connect-openapi plugin
+
+## Prerequisites
+
+- `protoc` installed ([install guide](https://github.com/protocolbuffers/protobuf/releases))
+- `protoc-gen-connect-openapi` installed:
+  ```bash
+  go install github.com/sudorandom/protoc-gen-connect-openapi@latest
+  ```
+
+## Usage
+
+```bash
+# Generate OpenAPI spec from proto files
+spec-forge generate ./my-grpc-project
+
+# With additional import paths
+spec-forge generate ./my-grpc-project --proto-import-path ./third_party --proto-import-path ./vendor
+
+# Generate with AI enrichment
+spec-forge generate ./my-grpc-project --language zh
+```
+
+## Limitations
+
+- **buf-managed projects are not supported** in this mode. Use `buf generate` with the plugin, then use `spec-forge enrich` on the generated OpenAPI spec.
+
+## References
+
+- [protoc-gen-connect-openapi](https://github.com/sudorandom/protoc-gen-connect-openapi)
+- [Protocol Buffers](https://protobuf.dev/)
diff --git a/docs/hertz.md b/docs/hertz.md
@@ -0,0 +1,22 @@
+# Hertz (CloudWeGo)
+
+Spec Forge will support generating OpenAPI specs from [Hertz](https://github.com/cloudwego/hertz) projects.
+
+## Current Status
+
+🚧 **Coming soon**
+
+## Recommended Tool
+
+The official CloudWeGo documentation for OpenAPI generation is outdated. For generating OpenAPI specs from Hertz projects, use:
+
+**[hertz-contrib/swagger-generate](https://github.com/hertz-contrib/swagger-generate)**
+
+Specifically: [`protoc-gen-http-swagger`](https://github.com/hertz-contrib/swagger-generate/tree/main/protoc-gen-http-swagger)
+
+This tool generates OpenAPI specs from Hertz HTTP annotations in proto files.
+
+## References
+
+- [Hertz GitHub](https://github.com/cloudwego/hertz)
+- [hertz-contrib/swagger-generate](https://github.com/hertz-contrib/swagger-generate)
diff --git a/docs/kitex.md b/docs/kitex.md
@@ -0,0 +1,22 @@
+# Kitex (CloudWeGo)
+
+Spec Forge will support generating OpenAPI specs from [Kitex](https://github.com/cloudwego/kitex) projects.
+
+## Current Status
+
+🚧 **Coming soon**
+
+## Recommended Tool
+
+The official CloudWeGo documentation for OpenAPI generation is outdated. For generating OpenAPI specs from Kitex projects, use:
+
+**[hertz-contrib/swagger-generate](https://github.com/hertz-contrib/swagger-generate)**
+
+Specifically: [`protoc-gen-rpc-swagger`](https://github.com/hertz-contrib/swagger-generate/tree/main/protoc-gen-rpc-swagger)
+
+This tool generates OpenAPI specs from Kitex RPC annotations in proto files.
+
+## References
+
+- [Kitex GitHub](https://github.com/cloudwego/kitex)
+- [hertz-contrib/swagger-generate](https://github.com/hertz-contrib/swagger-generate)