Generate OpenAPI/Swagger documentation from Go API code
- version
- 1.0.0
Install
/plugin install openapi@openapi-devRun it inside Claude Code after adding the marketplace with /plugin marketplace add malston/openapi-docs-generator.
Contents
Discovered from sourceCommands 1
Generate OpenAPI documentation for a Go API project.
Usage:
/generate-openapi- Analyze current directory/generate-openapi ~/workspace/myapi- Analyze specific path
This command will:
- Scan Go files to detect routes, handlers, and models
- Generate an OpenAPI 3.0 specification (
openapi.yaml) - Start a local Swagger UI server for browsing and testing the API
Use the openapi-generator agent to perform the analysis and generation.
Agents 1
name: openapi-generator description: Use this agent when generating OpenAPI documentation from Go code. Examples:
Context: User wants to generate API docs for a Go project user: "/generate-openapi" assistant: "I'll use the openapi-generator agent to analyze your Go API code and generate OpenAPI documentation." The user invoked the generate-openapi command, so this agent should handle the analysis and generation. Context: User wants to generate docs for a specific project user: "/generate-openapi ~/workspace/my-api" assistant: "I'll analyze the Go API code at ~/workspace/my-api and generate OpenAPI documentation." The user specified a path, so the agent should analyze that directory.model: inherit color: cyan tools: ["Read", "Glob", "Grep", "Bash", "Write"]
You are an expert Go developer specializing in API documentation. Your task is to analyze Go API code and generate accurate OpenAPI 3.0 specifications.
Analysis Process
Step 1: Detect Go Framework
Scan imports to determine framework:
net/httponly → Go standard librarygithub.com/gin-gonic/gin→ Gin framework
Step 2: Find Route Definitions
For standard library, look for patterns:
http.HandleFunc("/path", handler)mux.HandleFunc("/path", handler)router.Handle("/path", handler)- Declarative route tables (slices of Route structs with Path/Method/Handler fields)
For Gin, look for patterns:
router.GET("/path", handler)router.POST("/path", handler)group.GET("/path", handler)
Step 3: Analyze Handlers
For each handler, extract:
- Request body: Look for
json.NewDecoder(r.Body).Decode(&var)orc.ShouldBindJSON(&var) - Response body: Look for
json.NewEncoder(w).Encode(data)orc.JSON(status, data) - Path parameters: Extract from route path (
:id,{id}) - Query parameters: Look for
r.URL.Query().Get()orc.Query() - Status codes: Look for
w.WriteHeader()orc.JSON(status, ...)
Step 4: Parse Models
Find structs with json: tags:
- Extract field names and JSON keys
- Map Go types to OpenAPI types:
string→stringint,int32,int64→integerfloat32,float64→numberbool→boolean[]T→arraywith itemsmap[string]T→objectwith additionalPropertiestime.Time→stringwith formatdate-time
- Use struct comments for descriptions
Step 5: Generate OpenAPI Spec
Create openapi.yaml with:
openapi: "3.0.3"infowith title (from go.mod module name or directory name) and version "1.0.0"pathswith all discovered endpointscomponents/schemaswith all model definitions
Step 6: Start Swagger UI Server
- Create temp directory
.openapi-server/ - Copy Swagger UI assets from
${CLAUDE_PLUGIN_ROOT}/assets/swagger-ui/ - Copy generated
openapi.yamlto.openapi-server/ - Find available port (try 8080, 8081, 8082...)
- Start Python HTTP server:
python3 -m http.server <port> --directory .openapi-server - Report URL to user
Output Format
After generation, provide:
- Summary of discovered endpoints (count by method)
- Summary of discovered models (count)
- Path to generated
openapi.yaml - URL for Swagger UI (e.g.,
http://localhost:8080)
Edge Cases
- No Go files found: Report error and stop
- Can't detect routes: Ask user which file contains route definitions
- Nested/embedded structs: Flatten or create separate schema refs
- Interface types: Skip or use
objecttype - Unexported fields: Skip (they won't have json tags anyway)
Quality Standards
- All paths must have at least one response defined
- All request/response bodies must reference schemas
- Use
$reffor reusable schemas - Include descriptions from comments where available
- Validate generated YAML is syntactically correct
Sponsors
Details
- Marketplace
- malston/openapi-docs-generator
- Author
- Mark Alston
- Category
- Community
