webkit-bindings-api.yaml RawHistoryFolder
1openapi: 3.0.3
2info:
3 title: WebKit2GTK Go Bindings API
4 description: Contract for pkg/webkit Go bindings to WebKit2GTK native browser engine
5 version: 1.0.0
6 contact:
7 name: Dumber Browser WebKit Integration
8
9paths:
10 # Note: This is a native library API, not REST endpoints
11 # These represent Go function signatures for contract testing
12
13components:
14 schemas:
15 WebViewConfig:
16 type: object
17 properties:
18 width:
19 type: integer
20 minimum: 800
21 description: Initial window width
22 height:
23 type: integer
24 minimum: 600
25 description: Initial window height
26 userAgent:
27 type: string
28 description: Browser user agent string
29 enableDevTools:
30 type: boolean
31 default: true
32 description: Enable WebKit developer tools
33 enableJavaScript:
34 type: boolean
35 default: true
36 description: Enable JavaScript execution
37 required:
38 - width
39 - height
40
41 NavigationRequest:
42 type: object
43 properties:
44 url:
45 type: string
46 format: uri
47 description: Target URL for navigation
48 timeout:
49 type: integer
50 default: 30000
51 description: Navigation timeout in milliseconds
52 required:
53 - url
54
55 NavigationResult:
56 type: object
57 properties:
58 success:
59 type: boolean
60 description: Navigation success status
61 finalURL:
62 type: string
63 format: uri
64 description: Final URL after redirects
65 loadTime:
66 type: integer
67 description: Page load time in milliseconds
68 error:
69 type: string
70 nullable: true
71 description: Error message if navigation failed
72
73 KeyboardShortcut:
74 type: object
75 properties:
76 modifiers:
77 type: array
78 items:
79 type: string
80 enum: [ctrl, alt, shift, cmd]
81 description: Modifier keys required
82 key:
83 type: string
84 description: Primary key (e.g., 'c', 'Left', 'Right')
85 action:
86 type: string
87 enum: [navigate_back, navigate_forward, copy_url, zoom_in, zoom_out, zoom_reset]
88 description: Action to perform
89 required:
90 - key
91 - action
92
93 ScriptInjectionRequest:
94 type: object
95 properties:
96 script:
97 type: string
98 description: JavaScript code to inject
99 runAtEnd:
100 type: boolean
101 default: false
102 description: Run script after DOM content loaded
103 worldName:
104 type: string
105 default: "dumber-browser"
106 description: WebKit user script world name
107 required:
108 - script
109
110 ScriptInjectionResult:
111 type: object
112 properties:
113 success:
114 type: boolean
115 description: Script injection success status
116 error:
117 type: string
118 nullable: true
119 description: Error message if injection failed
120
121 ZoomRequest:
122 type: object
123 properties:
124 level:
125 type: number
126 minimum: 0.25
127 maximum: 5.0
128 description: Zoom level (1.0 = 100%)
129 required:
130 - level
131
132 ZoomResult:
133 type: object
134 properties:
135 success:
136 type: boolean
137 description: Zoom operation success status
138 actualLevel:
139 type: number
140 description: Actual zoom level set by WebKit
141 error:
142 type: string
143 nullable: true
144 description: Error message if zoom failed
145
146 BrowserError:
147 type: object
148 properties:
149 code:
150 type: string
151 enum: [
152 WEBKIT_INIT_FAILED,
153 GTK_INIT_FAILED,
154 NAVIGATION_FAILED,
155 SCRIPT_INJECTION_FAILED,
156 KEYBOARD_BINDING_FAILED,
157 MEMORY_LIMIT_EXCEEDED
158 ]
159 message:
160 type: string
161 description: Human-readable error message
162 details:
163 type: string
164 nullable: true
165 description: Technical error details
166 required:
167 - code
168 - message
169
170# Contract Test Functions (Go function signatures)
171# These will be implemented as integration tests
172
173x-go-functions:
174
175 # WebView Management
176 NewWebView:
177 description: Create new WebKit browser instance
178 parameters:
179 - name: config
180 schema: WebViewConfig
181 returns:
182 - name: webview
183 type: "*WebView"
184 - name: error
185 type: error
186
187 LoadURL:
188 description: Navigate to specified URL
189 parameters:
190 - name: webview
191 type: "*WebView"
192 - name: request
193 schema: NavigationRequest
194 returns:
195 - name: result
196 schema: NavigationResult
197 - name: error
198 type: error
199
200 # Keyboard Shortcuts
201 RegisterKeyboardShortcut:
202 description: Register keyboard shortcut handler
203 parameters:
204 - name: webview
205 type: "*WebView"
206 - name: shortcut
207 schema: KeyboardShortcut
208 - name: callback
209 type: "func()"
210 returns:
211 - name: error
212 type: error
213
214 # Script Injection
215 InjectScript:
216 description: Inject JavaScript into current page
217 parameters:
218 - name: webview
219 type: "*WebView"
220 - name: request
221 schema: ScriptInjectionRequest
222 returns:
223 - name: result
224 schema: ScriptInjectionResult
225 - name: error
226 type: error
227
228 # Zoom Control
229 SetZoom:
230 description: Set browser zoom level
231 parameters:
232 - name: webview
233 type: "*WebView"
234 - name: request
235 schema: ZoomRequest
236 returns:
237 - name: result
238 schema: ZoomResult
239 - name: error
240 type: error
241
242 GetZoom:
243 description: Get current browser zoom level
244 parameters:
245 - name: webview
246 type: "*WebView"
247 returns:
248 - name: level
249 type: float64
250 - name: error
251 type: error
252
253 # Lifecycle Management
254 Show:
255 description: Display browser window
256 parameters:
257 - name: webview
258 type: "*WebView"
259 returns:
260 - name: error
261 type: error
262
263 Hide:
264 description: Hide browser window
265 parameters:
266 - name: webview
267 type: "*WebView"
268 returns:
269 - name: error
270 type: error
271
272 Destroy:
273 description: Clean up browser resources
274 parameters:
275 - name: webview
276 type: "*WebView"
277 returns:
278 - name: error
279 type: error