Add OpenAPI 3.1 WebDriver API specification and skeleton controllers #156

Copilot · 2025-11-26T16:34:17Z

Adds a WebDriver-style REST API skeleton for Browser4 to enable SDK generation and front-end integration. Mock implementation only—no real browser integration.

OpenAPI Specification

openapi/openapi.yaml — Full OpenAPI 3.1 spec covering session, navigation, selectors, elements, scripts, control, and events
Served at /openapi.yaml and Swagger UI at /swagger-ui.html

Controllers (`pulsar-rest/.../webdriver/controller/`)

SessionController — POST/GET/DELETE /session/{sessionId}
NavigationController — URL, documentUri, baseUri operations
SelectorController — CSS-based: exists, waitFor, element(s), click, fill, press, outerHtml, screenshot
ElementController — W3C WebDriver: find, click, value, attribute, text
ScriptController — execute/sync, execute/async
ControlController — delay, pause, stop
EventsController — event-configs, events, subscribe

Data Layer

InMemoryStore — Thread-safe session/element/event storage using ConcurrentHashMap
DTOs in ApiDtos.kt following WebDriver response format {"value": ...}

Dependencies

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
</dependency>

Example Usage

# Create session
curl -X POST localhost:8182/session -H "Content-Type: application/json" \
  -d '{"capabilities": {"browserName": "chrome"}}'

# Navigate
curl -X POST localhost:8182/session/{id}/url -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

# Check element exists
curl -X POST localhost:8182/session/{id}/selectors/exists \
  -d '{"selector": "#submit"}'

Tests

12 integration tests in WebDriverApiIntegrationTest covering main flows.

Limitations: All operations return mock data. Real browser integration in subsequent PRs.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

accounts.google.com
- Triggering command: /proc/self/exe /proc/self/exe --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=none --ignore-certificate-errors --use-angle=swiftshader-webgl --mute-audio --ignore-certificate-errors --crashpad-handler-pid=7542 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/pulsar-REDACTED/context/groups/test/PULSAR_CHROME/cx.1 --change-stack-guard-on-fork=enable --shared-files=v8_context_snapshot_data:100 --field-trial-handle=3,i,2140587143764249571,10893657109407050990,262144 --disable-features=PaintHolding --variations-seed-version --trace-process-track-uuid=3190708989122997041 (dns block)
- Triggering command: /opt/google/chrome/chrome /usr/bin/google-chrome-stable --headless --disable-gpu --hide-scrollbars --remote-debugging-port=0 --no-default-browser-check --no-first-run --no-startup-window --mute-audio --disable-REDACTED-networking --disable-REDACTED-timer-throttling --disable-client-side-phishing-detection --disable-hang-monitor --disable-popup-blocking --disable-prompt-on-repost --disable-sync --disable-translate --disable-geolocation --disable-blink-features=AutomationControlled --metrics-recording-only (dns block)
- Triggering command: /proc/self/exe /proc/self/exe --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=none --ignore-certificate-errors --use-angle=swiftshader-webgl --mute-audio --ignore-certificate-errors --crashpad-handler-pid=7718 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/pulsar-REDACTED/context/groups/test/PULSAR_CHROME/cx.10 --change-stack-guard-on-fork=enable --shared-files=v8_context_snapshot_data:100 --field-trial-handle=3,i,2689884824601609872,5732397844315869094,262144 --disable-features=PaintHolding --variations-seed-version --trace-process-track-uuid=3190708989122997041 (dns block)
android.clients.google.com
- Triggering command: /proc/self/exe /proc/self/exe --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=none --ignore-certificate-errors --use-angle=swiftshader-webgl --mute-audio --ignore-certificate-errors --crashpad-handler-pid=7542 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/pulsar-REDACTED/context/groups/test/PULSAR_CHROME/cx.1 --change-stack-guard-on-fork=enable --shared-files=v8_context_snapshot_data:100 --field-trial-handle=3,i,2140587143764249571,10893657109407050990,262144 --disable-features=PaintHolding --variations-seed-version --trace-process-track-uuid=3190708989122997041 (dns block)
- Triggering command: /opt/google/chrome/chrome /usr/bin/google-chrome-stable --headless --disable-gpu --hide-scrollbars --remote-debugging-port=0 --no-default-browser-check --no-first-run --no-startup-window --mute-audio --disable-REDACTED-networking --disable-REDACTED-timer-throttling --disable-client-side-phishing-detection --disable-hang-monitor --disable-popup-blocking --disable-prompt-on-repost --disable-sync --disable-translate --disable-geolocation --disable-blink-features=AutomationControlled --metrics-recording-only (dns block)
- Triggering command: /proc/self/exe /proc/self/exe --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=none --ignore-certificate-errors --use-angle=swiftshader-webgl --mute-audio --ignore-certificate-errors --crashpad-handler-pid=7718 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/pulsar-REDACTED/context/groups/test/PULSAR_CHROME/cx.10 --change-stack-guard-on-fork=enable --shared-files=v8_context_snapshot_data:100 --field-trial-handle=3,i,2689884824601609872,5732397844315869094,262144 --disable-features=PaintHolding --variations-seed-version --trace-process-track-uuid=3190708989122997041 (dns block)
ark.cn-beijing.volces.com
- Triggering command: /usr/lib/jvm/temurin-17-jdk-amd64/bin/java /usr/lib/jvm/temurin-17-jdk-amd64/bin/java -XX:+EnableDynamicAgentLoading -jar /home/REDACTED/work/Browser4/Browser4/pulsar-core/pulsar-third/pulsar-llm/target/surefire/surefirebooter-20251126165353434_78.jar /home/REDACTED/work/Browser4/Browser4/pulsar-core/pulsar-third/pulsar-llm/target/surefire 2025-11-26T16-52-32_105-jvmRun1 surefire-20251126165353434_76tmp surefire_6-20251126165353434_77tmp (dns block)
clients2.google.com
- Triggering command: /proc/self/exe /proc/self/exe --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=none --ignore-certificate-errors --use-angle=swiftshader-webgl --mute-audio --ignore-certificate-errors --crashpad-handler-pid=7542 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/pulsar-REDACTED/context/groups/test/PULSAR_CHROME/cx.1 --change-stack-guard-on-fork=enable --shared-files=v8_context_snapshot_data:100 --field-trial-handle=3,i,2140587143764249571,10893657109407050990,262144 --disable-features=PaintHolding --variations-seed-version --trace-process-track-uuid=3190708989122997041 (dns block)
- Triggering command: /opt/google/chrome/chrome /usr/bin/google-chrome-stable --headless --disable-gpu --hide-scrollbars --remote-debugging-port=0 --no-default-browser-check --no-first-run --no-startup-window --mute-audio --disable-REDACTED-networking --disable-REDACTED-timer-throttling --disable-client-side-phishing-detection --disable-hang-monitor --disable-popup-blocking --disable-prompt-on-repost --disable-sync --disable-translate --disable-geolocation --disable-blink-features=AutomationControlled --metrics-recording-only (dns block)
- Triggering command: /proc/self/exe /proc/self/exe --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=none --ignore-certificate-errors --use-angle=swiftshader-webgl --mute-audio --ignore-certificate-errors --crashpad-handler-pid=7718 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/pulsar-REDACTED/context/groups/test/PULSAR_CHROME/cx.10 --change-stack-guard-on-fork=enable --shared-files=v8_context_snapshot_data:100 --field-trial-handle=3,i,2689884824601609872,5732397844315869094,262144 --disable-features=PaintHolding --variations-seed-version --trace-process-track-uuid=3190708989122997041 (dns block)
example.com
- Triggering command: /usr/lib/jvm/temurin-17-jdk-amd64/bin/java /usr/lib/jvm/temurin-17-jdk-amd64/bin/java -XX:+EnableDynamicAgentLoading -jar /home/REDACTED/work/Browser4/Browser4/pulsar-core/pulsar-common/target/surefire/surefirebooter-20251126165236131_3.jar /home/REDACTED/work/Browser4/Browser4/pulsar-core/pulsar-common/target/surefire 2025-11-26T16-52-32_105-jvmRun1 surefire-20251126165236131_1tmp surefire_0-20251126165236131_2tmp (dns block)
google.com
- Triggering command: /proc/self/exe /proc/self/exe --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=none --ignore-certificate-errors --use-angle=swiftshader-webgl --mute-audio --ignore-certificate-errors --crashpad-handler-pid=7542 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/pulsar-REDACTED/context/groups/test/PULSAR_CHROME/cx.1 --change-stack-guard-on-fork=enable --shared-files=v8_context_snapshot_data:100 --field-trial-handle=3,i,2140587143764249571,10893657109407050990,262144 --disable-features=PaintHolding --variations-seed-version --trace-process-track-uuid=3190708989122997041 (dns block)
- Triggering command: /proc/self/exe /proc/self/exe --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=none --ignore-certificate-errors --use-angle=swiftshader-webgl --mute-audio --ignore-certificate-errors --crashpad-handler-pid=7718 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/pulsar-REDACTED/context/groups/test/PULSAR_CHROME/cx.10 --change-stack-guard-on-fork=enable --shared-files=v8_context_snapshot_data:100 --field-trial-handle=3,i,2689884824601609872,5732397844315869094,262144 --disable-features=PaintHolding --variations-seed-version --trace-process-track-uuid=3190708989122997041 (dns block)
https://api.github.com//advisories
- Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node /home/REDACTED/work/_temp/ghcca-node/node/bin/node --enable-source-maps /home/REDACTED/work/_temp/copilot-developer-action-main/dist/index.js (http block)
safebrowsingohttpgateway.googleapis.com
- Triggering command: /proc/self/exe /proc/self/exe --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=none --ignore-certificate-errors --use-angle=swiftshader-webgl --mute-audio --ignore-certificate-errors --crashpad-handler-pid=7542 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/pulsar-REDACTED/context/groups/test/PULSAR_CHROME/cx.1 --change-stack-guard-on-fork=enable --shared-files=v8_context_snapshot_data:100 --field-trial-handle=3,i,2140587143764249571,10893657109407050990,262144 --disable-features=PaintHolding --variations-seed-version --trace-process-track-uuid=3190708989122997041 (dns block)
- Triggering command: /opt/google/chrome/chrome /usr/bin/google-chrome-stable --headless --disable-gpu --hide-scrollbars --remote-debugging-port=0 --no-default-browser-check --no-first-run --no-startup-window --mute-audio --disable-REDACTED-networking --disable-REDACTED-timer-throttling --disable-client-side-phishing-detection --disable-hang-monitor --disable-popup-blocking --disable-prompt-on-repost --disable-sync --disable-translate --disable-geolocation --disable-blink-features=AutomationControlled --metrics-recording-only (dns block)
- Triggering command: /proc/self/exe /proc/self/exe --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=none --ignore-certificate-errors --use-angle=swiftshader-webgl --mute-audio --ignore-certificate-errors --crashpad-handler-pid=7718 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/pulsar-REDACTED/context/groups/test/PULSAR_CHROME/cx.10 --change-stack-guard-on-fork=enable --shared-files=v8_context_snapshot_data:100 --field-trial-handle=3,i,2689884824601609872,5732397844315869094,262144 --disable-features=PaintHolding --variations-seed-version --trace-process-track-uuid=3190708989122997041 (dns block)
www.aliyun.com
- Triggering command: /proc/self/exe /proc/self/exe --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=none --ignore-certificate-errors --use-angle=swiftshader-webgl --mute-audio --ignore-certificate-errors --crashpad-handler-pid=7718 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/pulsar-REDACTED/context/groups/test/PULSAR_CHROME/cx.10 --change-stack-guard-on-fork=enable --shared-files=v8_context_snapshot_data:100 --field-trial-handle=3,i,2689884824601609872,5732397844315869094,262144 --disable-features=PaintHolding --variations-seed-version --trace-process-track-uuid=3190708989122997041 (dns block)
- Triggering command: /opt/google/chrome/chrome /usr/bin/google-chrome-stable --headless --disable-gpu --hide-scrollbars --remote-debugging-port=0 --no-default-browser-check --no-first-run --no-startup-window --mute-audio --disable-REDACTED-networking --disable-REDACTED-timer-throttling --disable-client-side-phishing-detection --disable-hang-monitor --disable-popup-blocking --disable-prompt-on-repost --disable-sync --disable-translate --disable-geolocation --disable-blink-features=AutomationControlled --metrics-recording-only (dns block)
www.baidu.com
- Triggering command: /proc/self/exe /proc/self/exe --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=none --ignore-certificate-errors --use-angle=swiftshader-webgl --mute-audio --ignore-certificate-errors --crashpad-handler-pid=7542 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/pulsar-REDACTED/context/groups/test/PULSAR_CHROME/cx.1 --change-stack-guard-on-fork=enable --shared-files=v8_context_snapshot_data:100 --field-trial-handle=3,i,2140587143764249571,10893657109407050990,262144 --disable-features=PaintHolding --variations-seed-version --trace-process-track-uuid=3190708989122997041 (dns block)
- Triggering command: /opt/google/chrome/chrome /usr/bin/google-chrome-stable --headless --disable-gpu --hide-scrollbars --remote-debugging-port=0 --no-default-browser-check --no-first-run --no-startup-window --mute-audio --disable-REDACTED-networking --disable-REDACTED-timer-throttling --disable-client-side-phishing-detection --disable-hang-monitor --disable-popup-blocking --disable-prompt-on-repost --disable-sync --disable-translate --disable-geolocation --disable-blink-features=AutomationControlled --metrics-recording-only (dns block)
www.dongqiudi.com
- Triggering command: /usr/lib/jvm/temurin-17-jdk-amd64/bin/java /usr/lib/jvm/temurin-17-jdk-amd64/bin/java -XX:+EnableDynamicAgentLoading -jar /home/REDACTED/work/Browser4/Browser4/pulsar-core/pulsar-common/target/surefire/surefirebooter-20251126165236131_3.jar /home/REDACTED/work/Browser4/Browser4/pulsar-core/pulsar-common/target/surefire 2025-11-26T16-52-32_105-jvmRun1 surefire-20251126165236131_1tmp surefire_0-20251126165236131_2tmp (dns block)
www.google.com
- Triggering command: /proc/self/exe /proc/self/exe --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=none --ignore-certificate-errors --use-angle=swiftshader-webgl --mute-audio --ignore-certificate-errors --crashpad-handler-pid=7542 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/pulsar-REDACTED/context/groups/test/PULSAR_CHROME/cx.1 --change-stack-guard-on-fork=enable --shared-files=v8_context_snapshot_data:100 --field-trial-handle=3,i,2140587143764249571,10893657109407050990,262144 --disable-features=PaintHolding --variations-seed-version --trace-process-track-uuid=3190708989122997041 (dns block)
- Triggering command: /opt/google/chrome/chrome /usr/bin/google-chrome-stable --headless --disable-gpu --hide-scrollbars --remote-debugging-port=0 --no-default-browser-check --no-first-run --no-startup-window --mute-audio --disable-REDACTED-networking --disable-REDACTED-timer-throttling --disable-client-side-phishing-detection --disable-hang-monitor --disable-popup-blocking --disable-prompt-on-repost --disable-sync --disable-translate --disable-geolocation --disable-blink-features=AutomationControlled --metrics-recording-only (dns block)
- Triggering command: /proc/self/exe /proc/self/exe --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=none --ignore-certificate-errors --use-angle=swiftshader-webgl --mute-audio --ignore-certificate-errors --crashpad-handler-pid=7718 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/pulsar-REDACTED/context/groups/test/PULSAR_CHROME/cx.10 --change-stack-guard-on-fork=enable --shared-files=v8_context_snapshot_data:100 --field-trial-handle=3,i,2689884824601609872,5732397844315869094,262144 --disable-features=PaintHolding --variations-seed-version --trace-process-track-uuid=3190708989122997041 (dns block)
www.xiaohongshu.com
- Triggering command: /proc/self/exe /proc/self/exe --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=none --ignore-certificate-errors --use-angle=swiftshader-webgl --mute-audio --ignore-certificate-errors --crashpad-handler-pid=7542 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/pulsar-REDACTED/context/groups/test/PULSAR_CHROME/cx.1 --change-stack-guard-on-fork=enable --shared-files=v8_context_snapshot_data:100 --field-trial-handle=3,i,2140587143764249571,10893657109407050990,262144 --disable-features=PaintHolding --variations-seed-version --trace-process-track-uuid=3190708989122997041 (dns block)
- Triggering command: /opt/google/chrome/chrome /usr/bin/google-chrome-stable --headless --disable-gpu --hide-scrollbars --remote-debugging-port=0 --no-default-browser-check --no-first-run --no-startup-window --mute-audio --disable-REDACTED-networking --disable-REDACTED-timer-throttling --disable-client-side-phishing-detection --disable-hang-monitor --disable-popup-blocking --disable-prompt-on-repost --disable-sync --disable-translate --disable-geolocation --disable-blink-features=AutomationControlled --metrics-recording-only (dns block)
- Triggering command: /proc/self/exe /proc/self/exe --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=none --ignore-certificate-errors --use-angle=swiftshader-webgl --mute-audio --ignore-certificate-errors --crashpad-handler-pid=7718 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/pulsar-REDACTED/context/groups/test/PULSAR_CHROME/cx.10 --change-stack-guard-on-fork=enable --shared-files=v8_context_snapshot_data:100 --field-trial-handle=3,i,2689884824601609872,5732397844315869094,262144 --disable-features=PaintHolding --variations-seed-version --trace-process-track-uuid=3190708989122997041 (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

目标：在 platonai/Browser4 仓库中新建分支 feature/openapi-webdriver-api 并创建一个 Pull Request。PR 内容为：

新增 OpenAPI 规范文件

文件：openapi/openapi.yaml

内容：使用 OpenAPI 3.1 (skeleton)，包含之前讨论的 paths 和 components（session、navigation、selectors、element、interactions、screenshot、execute、control、events 等）。

在服务中通过静态资源或 controller 暴露为 /openapi.yaml。

在 pulsar-rest 模块添加 Spring Boot 服务端骨架（Kotlin）：

新增 Spring Boot 主类：pulsar-rest/src/main/kotlin/ai/platon/pulsar/rest/PulsarRestApplication.kt

新增 InMemoryStore：pulsar-rest/src/main/kotlin/ai/platon/pulsar/rest/store/InMemoryStore.kt

新增 DTO：pulsar-rest/src/main/kotlin/ai/platon/pulsar/rest/api/dto/ApiDtos.kt（包含 NewSessionRequest/Response, SetUrlRequest, SelectorRef, ElementRef, EventConfig, Event, ErrorResponse 等）

新增 Controllers：

SessionController (POST /session, DELETE /session/{sessionId}, GET /session/{sessionId})

NavigationController (POST /session/{sessionId}/url, GET /session/{sessionId}/url, GET /session/{sessionId}/documentUri, GET /session/{sessionId}/baseUri)

SelectorController (POST /session/{sessionId}/selectors/exists, /waitFor, /element, /elements, /click, /fill, /press, /outerHtml, /screenshot)

ElementController (POST /session/{sessionId}/element, /elements, POST /session/{sessionId}/element/{elementId}/click, /value, GET attribute/text)

ScriptController (POST /session/{sessionId}/execute/sync and /async)

ControlController (POST /session/{sessionId}/control/delay, /pause, /stop)

EventsController (POST/GET /session/{sessionId}/event-configs, GET /session/{sessionId}/events, POST /session/{sessionId}/events/subscribe)

Controller behavior: basic validation, use InMemoryStore for sessions/elements/event-configs/subscriptions, selector endpoints create mock ElementRef via hashing selector.

Return shapes must follow WebDriver style responses: { "value": ... } per OpenAPI.

集成 Swagger UI（springdoc-openapi）

在 pulsar-rest pom 添加 dependency: org.springdoc:springdoc-openapi-ui

自动提供 Swagger UI at /swagger-ui.html and OpenAPI JSON/YAML endpoints. Also expose /openapi.yaml (serve file from openapi/).

Tests

Add basic integration tests in pulsar-rest/src/test/kotlin/... to verify create session, navigate, selectors/exists and find element endpoints return 200 and expected response shapes. Use SpringBootTest with random port and TestRestTemplate or MockMvc.

Build / CI

Modify pulsar-rest/pom.xml to include spring-boot-starter-web, jackson-module-kotlin, springdoc-openapi-ui and spring-boot-starter-test for tests. Do not change parent versions; keep changes minimal.

Documentation & PR description

PR description must include implemented endpoints, files added, mock behavior limitations (no real browser integration), how to run tests and example curl commands for common flows (create session, navigate, selectors/exists, selectors/click).

Implementation constraints:

Keep changes limited to pulsar-rest and openapi/ files. Do not modify core modules outside those locations.

Ensure code compiles and tests run (unit/integration). If build fails due to project-specific POM constraints, report blockers in PR description.

Add logs at debug level for incoming requests; include X-Request-Id header in responses when feasible.

Deliverable: Create branch feature/openapi-webdriver-api off master, commit files, push branch, open PR against master with title and description above.

If any blocking issue (missing pulsar-rest module, incompatible build config, or CI failures), stop and report in PR description with clear reproduction steps and error messages.

Notes for reviewers: This PR provides a mocked skeleton to let front-end/SDK teams start using the OpenAPI and generating SDKs. Full browser integration to be implemented in subsequent PRs.

This pull request was created as a result of the following prompt from Copilot chat.

目标：在 platonai/Browser4 仓库中新建分支 feature/openapi-webdriver-api 并创建一个 Pull Request。PR 内容为：

新增 OpenAPI 规范文件

文件：openapi/openapi.yaml

内容：使用 OpenAPI 3.1 (skeleton)，包含之前讨论的 paths 和 components（session、navigation、selectors、element、interactions、screenshot、execute、control、events 等）。

在服务中通过静态资源或 controller 暴露为 /openapi.yaml。

在 pulsar-rest 模块添加 Spring Boot 服务端骨架（Kotlin）：

新增 Spring Boot 主类：pulsar-rest/src/main/kotlin/ai/platon/pulsar/rest/PulsarRestApplication.kt

新增 InMemoryStore：pulsar-rest/src/main/kotlin/ai/platon/pulsar/rest/store/InMemoryStore.kt

新增 DTO：pulsar-rest/src/main/kotlin/ai/platon/pulsar/rest/api/dto/ApiDtos.kt（包含 NewSessionRequest/Response, SetUrlRequest, SelectorRef, ElementRef, EventConfig, Event, ErrorResponse 等）

新增 Controllers：

SessionController (POST /session, DELETE /session/{sessionId}, GET /session/{sessionId})

NavigationController (POST /session/{sessionId}/url, GET /session/{sessionId}/url, GET /session/{sessionId}/documentUri, GET /session/{sessionId}/baseUri)

SelectorController (POST /session/{sessionId}/selectors/exists, /waitFor, /element, /elements, /click, /fill, /press, /outerHtml, /screenshot)

ElementController (POST /session/{sessionId}/element, /elements, POST /session/{sessionId}/element/{elementId}/click, /value, GET attribute/text)

ScriptController (POST /session/{sessionId}/execute/sync and /async)

ControlController (POST /session/{sessionId}/control/delay, /pause, /stop)

EventsController (POST/GET /session/{sessionId}/event-configs, GET /session/{sessionId}/events, POST /session/{sessionId}/events/subscribe)

Controller behavior: basic validation, use InMemoryStore for sessions/elements/event-configs/subscriptions, selector endpoints create mock ElementRef via hashing selector.

Return shapes must follow WebDriver style responses: { "value": ... } per OpenAPI.

集成 Swagger UI（springdoc-openapi）

在 pulsar-rest pom 添加 dependency: org.springdoc:springdoc-openapi-ui

自动提供 Swagger UI at /swagger-ui.html and OpenAPI JSON/YAML endpoints. Also expose /openapi.yaml (serve file from openapi/).

Tests

Add basic integration tests in pulsar-rest/src/test/kotlin/... to verify create session, navigate, selectors/exists and find element endpoints return 200 and expected response shapes. Use SpringBootTest with random port and TestRestTemplate or MockMvc.

Build / CI

Modify pulsar-rest/pom.xml to include spring-boot-starter-web, jackson-module-kotlin, springdoc-openapi-ui and spring-boot-starter-test for tests. Do not change parent versions; keep changes minimal.

Documentation & PR description

PR description must include implemented endpoints, files added, mock behavior limitations (no real browser integration), how to run tests and example curl commands for common flows (create session, navigate, selectors/exists, selectors/click).

Implementation constraints:

Keep changes limited to pulsar-rest and openapi/ files. Do not modify core modules outside those locations.

Ensure code compiles and tests run (unit/integration). If build fails due to project-specific POM constraints, report blockers in PR description.

Add logs at debug level for incoming requests; include X-Request-Id header in responses when feasible.

Deliverable: Create branch feature/openapi-webdriver-api off master, commit files, push branch, open PR against master with title and description above.

If any blocking issue (missing pulsar-rest module, incompatible build config, or CI failures), stop and report in PR description with clear reproduction steps and error messages.

Notes for reviewers: This PR provides a mocked skeleton to let front-end/SDK teams start using the OpenAPI and generating SDKs. Full browser integration to be implemented in subsequent PRs.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

… integration tests Co-authored-by: galaxyeye <[email protected]>

…hema, and add documentation comments Co-authored-by: galaxyeye <[email protected]>

Initial plan

0778290

Copilot AI assigned Copilot and galaxyeye Nov 26, 2025

Copilot started work on behalf of galaxyeye November 26, 2025 16:34 View session

Copilot AI and others added 2 commits November 26, 2025 16:48

Add OpenAPI specification and WebDriver API skeleton controllers with…

3b1c865

… integration tests Co-authored-by: galaxyeye <[email protected]>

Fix code review issues: improve element ID generation, fix OpenAPI sc…

9529213

…hema, and add documentation comments Co-authored-by: galaxyeye <[email protected]>

Copilot AI changed the title ~~[WIP] Add OpenAPI specification and Spring Boot skeleton in pulsar-rest~~ Add OpenAPI 3.1 WebDriver API specification and skeleton controllers Nov 26, 2025

Copilot AI requested a review from galaxyeye November 26, 2025 16:58

Copilot finished work on behalf of galaxyeye November 26, 2025 16:58

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add OpenAPI 3.1 WebDriver API specification and skeleton controllers #156

Add OpenAPI 3.1 WebDriver API specification and skeleton controllers #156

Uh oh!

Copilot AI commented Nov 26, 2025 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Add OpenAPI 3.1 WebDriver API specification and skeleton controllers #156

Are you sure you want to change the base?

Add OpenAPI 3.1 WebDriver API specification and skeleton controllers #156

Uh oh!

Conversation

Copilot AI commented Nov 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

OpenAPI Specification

Controllers (pulsar-rest/.../webdriver/controller/)

Data Layer

Dependencies

Example Usage

Tests

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Nov 26, 2025 •

edited

Loading

Controllers (`pulsar-rest/.../webdriver/controller/`)