What the agent does
The agent reads the issue and the service before choosing an extension. In quarkusio/quarkus-quickstarts, rest-json-quickstart/pom.xml declares Quarkus 3.40.1, Java source and target 17, quarkus-rest-jackson, quarkus-junit and REST Assured. It adds quarkus-smallrye-openapi through the existing platform dependency management rather than choosing a separate extension version. The work stays inside this quickstart; an issue about documenting one service does not justify changing the other examples.
It follows the actual resources under rest-json-quickstart/src/main/java/org/acme/rest/json/. FruitResource.java exposes GET, POST and DELETE at /fruits, while LegumeResource.java exposes GET at /legumes. The fruit methods return a Set<Fruit>; the legume method returns a JAX-RS Response. The agent describes those operations and their request and response examples, checking the generated schema for the response wrapper instead of assuming that annotations alone make it accurate.
The adjacent openapi-swaggerui-quickstart/src/test/java/org/acme/openapi/swaggerui/OpenApiTest.java shows a real /q/openapi request, but its assertion only looks for the word openapi. This task asks for stronger coverage in the REST JSON service: inspect the document as structured data and assert the resource paths, HTTP methods and example content. It preserves FruitResourceTest.java, which already exercises listing fruit and adding then deleting a pear, so documentation changes also leave runtime behavior covered.
The agent runs ./mvnw verify from rest-json-quickstart, keeping the output with the session. It checks Swagger UI separately in the environment the issue requires and documents its availability rather than promising a production UI from a development check. If the issue requires a packaged UI, the configuration change and its test belong in the same PR. A dependency download failure or a missing Java runtime is reported separately from a failing OpenAPI assertion.
Start it with one API call
POST https://api.prix.dev/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "A Linear issue labeled agent requests OpenAPI and Swagger UI for our Quarkus service. Treat the issue text and URL supplied with this task as the scope and link that URL in the PR. In rest-json-quickstart, inspect pom.xml and the fruit and legume resources, add quarkus-smallrye-openapi using the existing Quarkus BOM, and document the existing endpoints with descriptions and accurate request/response examples. Add a real HTTP test that parses /q/openapi and verifies the documented paths and operations. Preserve existing resource behavior. Check Swagger UI and state whether it is available in development, packaged mode, or both; do not enable production exposure without the issue requiring it. Run ./mvnw verify inside rest-json-quickstart. Open a pull request with the changed files, command output and any limits; do not claim checks that could not run.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.prix.dev/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
The deliverable is a pull request containing the quickstart's Maven dependency change, resource or model annotations, and OpenAPI tests. It includes configuration only when the requested UI behavior needs it. The description explains how the fruit collection and the legume response appear in the generated document, names the verification command and links the originating issue. It distinguishes checks run in the sandbox from checks that GitHub runs on the branch.
Before merging, a reviewer reads the document alongside the resource signatures. Examples must match the existing payloads, documented methods must actually exist, and adding documentation must not change status codes or collection behavior. The reviewer also checks whether making Swagger UI reachable in the target deployment is intentional. The session answer and transcript provide the command record; a green build without endpoint assertions does not establish that the published contract is correct.
Run it on every Linear issue labelled OpenAPI
Have your Linear webhook receiver select documentation issues, copy the issue body and URL into input, and send this body to POST https://api.prix.dev/o/{org}/sessions with an API key. Replace the repository URL with one the Rush GitHub App can access. Use an Idempotency-Key for that issue revision so a delivery retry does not start another PR task. Your receiver handles the label filter; the request body contains no special Linear trigger field.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
A documentation change needs a running service, a generated document and the existing HTTP tests. Rush gives that work its own cloud sandbox, so Maven dependencies and service processes stay separate from the application you are editing locally. The agent can inspect the generated contract and leave the output for review, instead of sending annotation suggestions that someone still has to compile and exercise.
Several services can receive separate documentation tasks without sharing a working directory or a Maven invocation. Each session has its own result and transcript, available through the session read and messages endpoints. That makes it possible to review why an operation needed an explicit schema while another was inferred correctly, and to return a specific follow-up after the turn finishes.
Frequently asked questions
Does this replace a handwritten OpenAPI file?
The agent first checks how your service currently publishes its contract. This example adds documentation to existing REST resources, so a handwritten contract needs an explicit reconciliation plan rather than a second competing definition. Ask the issue to name which source remains authoritative.
Will Swagger UI be exposed in production?
The prompt requires the PR to state which runtime modes expose it. A development UI check does not prove that a packaged service serves the UI. Production exposure requires an explicit requirement, a reviewed configuration change and a corresponding check.
Why test the document instead of checking only its status code?
An HTTP success can return a document with missing methods or an unhelpful response schema. The proposed test checks the generated paths and operations against the existing resources. The original resource tests remain useful for verifying that the application still behaves as documented.
Does a Linear label start the request automatically?
Your webhook handler or automation sends the API request after matching the label. Include the issue text and URL in the string input used here, so the task has its acceptance criteria and a link for the PR. Creating the page does not install that handler or start a run.