docs: add godoc for public api and readme response examples

Author: karust

README.md

@@ -82,7 +82,7 @@ API response example:
     "rank": 2,
     "url": "https://www.bing.com/ck/a?!&&p=6f15ac4589858d0a104cd6f55cc8",
     "title": "Golden Retriever Dog Forums",
-    "description": "Oct 20, 2024 · Back in the 1970s, Golden Retrievers routinely lived until 16 and 17 years old, they are now...",
+    "description": "Oct 20, 2024 · Back in the 1970s, Golden Retrievers routinely lived until 16 and 17 years old, they are now...",
     "ad": false,
     "engine": "bing"
   },
@@ -142,6 +142,87 @@ curl "http://127.0.0.1:7000/yandex/search?text=golang&limit=10&start=10"
 curl "http://127.0.0.1:7000/bing/image?text=golang&limit=20"
 ```
 
+## Response Examples
+
+Interactive docs (OpenAPI + Swagger UI) are available at:
+
+- `http://127.0.0.1:7000/docs`
+- `http://127.0.0.1:7000/openapi.yaml`
+
+### Web Search Response (`/<engine>/search`)
+
+```json
+[
+  {
+    "rank": 1,
+    "url": "https://go.dev/doc/",
+    "title": "Documentation - The Go Programming Language",
+    "description": "Official Go documentation, tutorials, references, and release notes.",
+    "ad": false
+  },
+  {
+    "rank": 2,
+    "url": "https://pkg.go.dev/",
+    "title": "pkg.go.dev",
+    "description": "Go package discovery and API documentation.",
+    "ad": false
+  }
+]
+```
+
+### Image Search Response (`/<engine>/image`)
+
+```json
+[
+  {
+    "rank": 1,
+    "url": "https://golang.org/lib/godoc/images/go-logo-blue.svg",
+    "title": "Go Gopher Logo",
+    "description": "Source: https://go.dev/brand/",
+    "ad": false
+  },
+  {
+    "rank": 2,
+    "url": "https://example.com/images/go-mascot.png",
+    "title": "Go mascot",
+    "description": "Height:800, Width:1200, Source Page: https://example.com/post",
+    "ad": false
+  }
+]
+```
+
+### Error Responses
+
+`400 Bad Request` (invalid/missing query):
+
+```json
+{
+  "error": "bad_request",
+  "code": 400,
+  "message": "Query cannot be empty"
+}
+```
+
+`503 Service Unavailable` (engine unavailable, captcha, timeout, or proxy path failure):
+
+```json
+{
+  "error": "service_unavailable",
+  "code": 503,
+  "message": "captcha found, please stop sending requests for a while: captcha detected"
+}
+```
+
+### Response Headers
+
+| Header              | Values/Examples                 | Meaning                                                       |
+| ------------------- | ------------------------------- | ------------------------------------------------------------- |
+| `X-Cache`           | `HIT`, `MISS`, `BYPASS`         | Cache result for this response.                               |
+| `X-Fallback-Engine` | `google`, `bing`, `duckduckgo`  | Present when dedicated endpoint used fallback engine.         |
+| `X-Proxy-Mode`      | `off`, `single`, `pool`         | Proxy policy mode applied by resilient search.                |
+| `X-Proxy-Tag`       | `residential`, `datacenter`, `` | Selected proxy pool tag. Empty when proxy mode is off/direct. |
+| `X-Proxy-Used`      | `direct`, `socks5://host:port`  | Actual upstream route used to execute request.                |
+
 ## 🌍 Proxy Support
 
 OpenSERP supports HTTP and SOCKS5 proxies.

baidu/search.go

@@ -31,12 +31,14 @@ type imageDataJson struct {
 	}
 }
 
+// Baidu implements core.SearchEngine for Baidu SERP pages.
 type Baidu struct {
 	core.Browser
 	core.SearchEngineOptions
 	logger *core.EngineLogger
 }
 
+// New creates a Baidu engine instance with browser/runtime options applied.
 func New(browser core.Browser, opts core.SearchEngineOptions) *Baidu {
 	baid := Baidu{Browser: browser}
 	opts.Init()
@@ -45,10 +47,12 @@ func New(browser core.Browser, opts core.SearchEngineOptions) *Baidu {
 	return &baid
 }
 
+// Name returns the stable engine identifier.
 func (baid *Baidu) Name() string {
 	return "baidu"
 }
 
+// GetRateLimiter returns a limiter configured from SearchEngineOptions.
 func (baid *Baidu) GetRateLimiter() *rate.Limiter {
 	ratelimit := rate.Every(baid.GetRatelimit())
 	return rate.NewLimiter(ratelimit, baid.RateBurst)
@@ -64,6 +68,8 @@ func (baid *Baidu) isTimeout(page *rod.Page) bool {
 	return err == nil
 }
 
+// Search executes a Baidu web search and returns normalized search results.
+// It may return core.ErrCaptcha or core.ErrSearchTimeout.
 func (baid *Baidu) Search(query core.Query) ([]core.SearchResult, error) {
 	baid.logger.Debug("Starting search, query: %+v", query)
 
@@ -145,6 +151,8 @@ func (baid *Baidu) Search(query core.Query) ([]core.SearchResult, error) {
 	return core.DeduplicateResults(searchResults), nil
 }
 
+// SearchImage executes a Baidu image search and returns normalized image
+// results. It may return core.ErrCaptcha or core.ErrSearchTimeout.
 func (baid *Baidu) SearchImage(query core.Query) ([]core.SearchResult, error) {
 	baid.logger.Debug("Starting image search, query: %+v", query)
 

baidu/url.go

@@ -22,6 +22,8 @@ func dateToTimestamp(date string) (int64, error) {
 	return t.Unix(), nil
 }
 
+// BuildURL builds a Baidu web search URL from Query fields.
+// It returns an error when query text, date, or pagination parameters are invalid.
 func BuildURL(q core.Query) (string, error) {
 	base, _ := url.Parse("https://www.baidu.com/")
 	base.Path += "s"
@@ -84,6 +86,8 @@ func BuildURL(q core.Query) (string, error) {
 	return base.String(), nil
 }
 
+// BuildImageURL builds a Baidu image search URL from Query fields and page
+// index. It returns an error when the query text is empty.
 func BuildImageURL(q core.Query, pageNum int) (string, error) {
 	base, _ := url.Parse("https://image.baidu.com/")
 	base.Path += "search/acjson"

bing/search.go

@@ -13,12 +13,14 @@ import (
 	"golang.org/x/time/rate"
 )
 
+// Bing implements core.SearchEngine for Bing SERP pages.
 type Bing struct {
 	core.Browser
 	core.SearchEngineOptions
 	logger *core.EngineLogger
 }
 
+// New creates a Bing engine instance with browser/runtime options applied.
 func New(browser core.Browser, opts core.SearchEngineOptions) *Bing {
 	bing := Bing{Browser: browser}
 	opts.Init()
@@ -27,10 +29,12 @@ func New(browser core.Browser, opts core.SearchEngineOptions) *Bing {
 	return &bing
 }
 
+// Name returns the stable engine identifier.
 func (bing *Bing) Name() string {
 	return "bing"
 }
 
+// GetRateLimiter returns a limiter configured from SearchEngineOptions.
 func (bing *Bing) GetRateLimiter() *rate.Limiter {
 	ratelimit := rate.Every(bing.GetRatelimit())
 	return rate.NewLimiter(ratelimit, bing.RateBurst)
@@ -99,6 +103,8 @@ func (bing *Bing) close(page *rod.Page) {
 	}
 }
 
+// Search executes a Bing web search and returns normalized search results.
+// It may return core.ErrCaptcha or core.ErrSearchTimeout.
 func (bing *Bing) Search(query core.Query) ([]core.SearchResult, error) {
 	bing.logger.Debug("Starting search, query: %+v", query)
 
@@ -240,7 +246,7 @@ func (bing *Bing) Search(query core.Query) ([]core.SearchResult, error) {
 	return deduped, nil
 }
 
-// BingImageData represents the JSON structure in the m attribute of image elements
+// BingImageData represents metadata encoded in the image result `m` attribute.
 type BingImageData struct {
 	T      string `json:"t"`      // Title
 	Desc   string `json:"desc"`   // Description
@@ -252,7 +258,8 @@ type BingImageData struct {
 	MURL   string `json:"murl"`   // Image URL
 }
 
-// SearchImage performs Bing image search and returns results
+// SearchImage executes a Bing image search and returns normalized image
+// results. It may return core.ErrCaptcha or core.ErrSearchTimeout.
 func (bing *Bing) SearchImage(query core.Query) ([]core.SearchResult, error) {
 	bing.logger.Debug("Starting image search, query: %+v", query)
 

bing/url.go

@@ -12,6 +12,8 @@ import (
 	"github.com/sirupsen/logrus"
 )
 
+// BuildURL builds a Bing web search URL from Query fields.
+// It returns an error when query text or date parameters are invalid.
 func BuildURL(q core.Query) (string, error) {
 	base, err := url.Parse("https://www.bing.com")
 	if err != nil {
@@ -93,6 +95,8 @@ func BuildURL(q core.Query) (string, error) {
 	return base.String(), nil
 }
 
+// BuildImageURL builds a Bing image search URL from Query fields.
+// It returns an error when the resulting query text is empty.
 func BuildImageURL(q core.Query) (string, error) {
 	base, err := url.Parse("https://www.bing.com")
 	if err != nil {

core/browser.go

@@ -17,23 +17,35 @@ import (
 	"github.com/sirupsen/logrus"
 )
 
+// BrowserOpts configures Chromium launch and navigation behavior.
 type BrowserOpts struct {
-	IsHeadless          bool          // Use browser interface
-	IsLeakless          bool          // Force to kill browser
-	Timeout             time.Duration // Timeout
-	LanguageCode        string
-	WaitRequests        bool          // Wait requests to complete after navigation
-	LeavePageOpen       bool          // Leave pages and browser open
-	WaitLoadTime        time.Duration // Time to wait till page loads
-	CaptchaSolverApiKey string        // 2Captcha api key
-	BrowserPath         string        // Explicit browser executable path
-	ProxyURL            string        // Proxy URL
-	Insecure            bool          // Allow insecure TLS connections
-	UseStealth          bool          // Use go-rod stealth plugin
-
+	// IsHeadless runs Chromium without visible UI.
+	IsHeadless bool
+	// IsLeakless forces child browser process cleanup when the parent exits.
+	IsLeakless bool
+	// Timeout is applied to browser connect and page navigation operations.
+	Timeout time.Duration
+	// LanguageCode sets Accept-Language for emulated requests.
+	LanguageCode string
+	// WaitRequests waits for request-idle state after navigation.
+	WaitRequests bool
+	// LeavePageOpen keeps pages open after search operations.
+	LeavePageOpen bool
+	// WaitLoadTime is an additional fixed wait after load/idle checks.
+	WaitLoadTime time.Duration
+	// CaptchaSolverApiKey enables 2Captcha integration for supported engines.
+	CaptchaSolverApiKey string
+	// BrowserPath optionally points to a specific browser executable.
+	BrowserPath string
+	// ProxyURL defines the upstream proxy for browser traffic.
+	ProxyURL string
+	// Insecure allows invalid TLS certificates for browser requests.
+	Insecure bool
+	// UseStealth enables go-rod stealth page creation.
+	UseStealth bool
 }
 
-// Initialize browser parameters with default values if they are not set
+// Check applies default option values when optional fields are unset.
 func (o *BrowserOpts) Check() {
 	if o.Timeout == 0 {
 		o.Timeout = time.Second * 30
@@ -44,13 +56,16 @@ func (o *BrowserOpts) Check() {
 	}
 }
 
+// Browser wraps a launched Chromium instance used by engine implementations.
 type Browser struct {
 	BrowserOpts
 	browserAddr   string
 	browser       *rod.Browser
 	CaptchaSolver *CaptchaSolver
 }
 
+// NewBrowser launches a new Chromium process via Rod launcher and returns a
+// Browser wrapper configured with proxy and captcha solver settings.
 func NewBrowser(opts BrowserOpts) (*Browser, error) {
 	opts.Check()
 	logrus.Debugf("Browser options: %+v", opts)
@@ -151,7 +166,7 @@ func resolveBrowserBinaryPath(browserPath string, lookPath func() (string, bool)
 	return "", nil
 }
 
-// Check whether browser instance is already created
+// IsInitialized reports whether the browser launcher has been created.
 func (b *Browser) IsInitialized() bool {
 	if b.browserAddr != "" {
 		return true
@@ -160,7 +175,9 @@ func (b *Browser) IsInitialized() bool {
 	}
 }
 
-// Open URL
+// Navigate connects to Chromium, creates a page, applies stealth/emulation and
+// proxy auth, then navigates to URL. It returns an initialized page ready for
+// selector queries, or an error when browser setup/navigation fails.
 func (b *Browser) Navigate(URL string) (*rod.Page, error) {
 	logrus.Debug("Navigate to: ", URL)
 
@@ -280,6 +297,7 @@ func (b *Browser) Navigate(URL string) (*rod.Page, error) {
 	return page, nil
 }
 
+// Close closes the active browser connection.
 func (b *Browser) Close() error {
 	return b.browser.Close()
 }