Add CLI api command for REST API calls to server

[wadimw]

Summary

Added a mojito api command (similar to gh api) that allows executing authenticated calls to the Mojito REST API, plus auto-generated OpenAPI spec served at /api-docs for endpoint discoverability.

The command makes authenticated HTTP requests to any Mojito endpoint, encapsulating auth, instance config, pollable task waiting, and pagination. Outputs clean JSON to stdout with diagnostics on stderr, suitable for piping to jq or consumption by scripts or AI agents.

API spec is generated automatically using springdoc-openapi. It's not a public API - there are no strict versioning policies, backwards compatibility guarantees etc.. This is exposed primarily to provide an AI agent with an entrypoint to discover existing capabilities without it deep-diving into Mojito's source code upfront.

Key design decisions

• Based on gh api - this approach was inspired by GitHub CLI api command (docs)
• Default method is always GET -- unlike gh api which auto-switches to POST when fields are present. This avoids accidental mutations since Mojito uses the same paths for GET (list) and POST (create). --input also requires explicit -X.
• stdout/stderr separation -- response body (including error bodies) always goes to stdout; error summaries, wait progress, and pagination resume hints go to stderr. (Compared to implementation of other Mojito CLI commands, this one bypasses ConsoleWriter entirely; we should consider refactoring CLI output implementation in future to allow structured output for existing commands).
• Field construction is intentionally flat -- -F/-f supports simple key=value and key[]=value (arrays). Complex nested structures (e.g. creating a repository with locales, posting screenshot runs) should use --input with pre-constructed JSON instead. This avoids the complexity of replicating gh api's deep nesting parser for a use case better served by jq + stdin.
• Pagination style auto-detection -- when --paginate is used, the command inspects the first response to determine which pagination style to use (Spring Data Page envelope vs bare JSON array), so --paginate-style doesn't need to be specified. Page size defaults to 10 to match server defaults.
• OpenAPI spec disabled by default -- springdoc.api-docs.enabled=false in application.properties. Enable with springdoc.api-docs.enabled=true for deployments that want agent discoverability.
• springdoc 2.2.0 -- pinned for Spring Boot 3.1.x compatibility. Uses -api artifact (no Swagger UI).

Features

Request construction:

• -X/--method -- explicit HTTP method (default: GET)
• -F/--field key=value -- typed fields (booleans, integers, nulls auto-converted; @file/@- for file/stdin)
• -f/--raw-field key=value -- string-only fields (no type conversion)
• key[]=value -- array construction (e.g. -F repositoryIds[]=1 -F repositoryIds[]=2)
• --input file -- pre-constructed body from file (- for stdin), requires explicit -X. Use for complex nested JSON.
• --binary -- raw byte mode for --input (e.g. image uploads)
• -H/--header key:value -- custom HTTP headers

Async operation support:

• --wait -- detects two async patterns and polls to completion:
  • PollableTask: responses with id + allFinished (top-level or nested pollableTask field). Used by most server-side async operations.
  • Polling token: responses with pollingToken.requestId. Poll URL is taken from pollingToken.pollUrl if present, otherwise derived as {requestPath}/results/{requestId}. Any endpoint can adopt this pattern. 120-attempt timeout.
• Gracefully passes through non-async responses (no error)

Pagination:

• --paginate enables automatic fetching of all pages. The pagination style is auto-detected from the first response:
  • JSON object with content + hasNext -> page mode (Spring Data Page/size)
  • JSON array -> offset mode (offset/limit, used by text unit search)
  • Neither -> not a paginated response, prints as-is and stops
• Without --paginate, only a single request is made (even if the endpoint supports pagination)
• --paginate-style optional override: auto (default), page, or offset
• --page-size (default: 10, matches server defaults), --max-pages (default: 10, 0=unlimited), --start-page (default: 0)
• --slurp to merge all pages into a single JSON array
• Resume hint printed to stderr when max-pages cap is reached

Output control:

• --pretty -- pretty-print JSON
• --silent -- suppress response body
• --include -- print HTTP status line and headers before body

API discoverability:

• springdoc-openapi auto-generates an OpenAPI spec from existing @RestController annotations, scoped to /api/**, with @JsonView support and serves it at /api-docs
• mojito api --spec fetches and prints the spec JSON (more idiomatic than a separate curl, encapsulates server's configured URL)

Usage examples

# Discover available endpoints
mojito api --spec --pretty

# List repositories
mojito api repositories

# Filter by name (fields go to query string on GET)
mojito api repositories -f name=my-repo

# Create a repository (explicit POST required, complex body via --input)
echo '{"name":"new-repo","description":"Test","repositoryLocales":[...]}' | \
  mojito api repositories -X POST --input -

# Simple POST with flat fields
mojito api repositories -X POST -f name=new-repo -f description="Test"

# Search text units (pagination auto-detected as offset style)
mojito api textunits/search -X POST --paginate --slurp \
  -F repositoryIds[]=42 -F searchType=CONTAINS -F source=hello

# Paginate drops (auto-detected as page style)
mojito api drops --paginate --page-size 20

# Wait for an async operation
mojito api thirdparty/sync -X POST -F repositoryId=42 --wait

# Upload a binary file
mojito api images/screenshot.png -X PUT --input screenshot.png --binary

Test plan

• Integration tests (38 total): GET, POST with raw/typed fields, explicit method override, field-to-query-string default, error responses (body on stdout, summary on stderr), page-style pagination, offset-style pagination, pagination auto-detection (both styles), --wait with non-pollable responses, custom headers, silent mode, pretty print, include headers
• Unit tests: endpoint normalization, PollableTask detection (top-level, nested, non-pollable), coerceValue type conversion (booleans, integers, nulls, raw mode), @file field values, array field construction, polling token detection, slurp merge output, stdin conflict validation (rawFields + --input)

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	maven/​org.springdoc/​springdoc-openapi-starter-webmvc-api@​2.2.0

View full report

[ehoogerbeets]

We are going to have to add @operation and @Schema tags throughout the backend API so that spring docs can extract it. We should start with the textunit search, repositories, pollable tasks APIs. (Should probably be a separate PR actually.)