Add jf api docs search for local OpenAPI operation discovery#3597
Open
ehl-jf wants to merge 5 commits into
Open
Add jf api docs search for local OpenAPI operation discovery#3597ehl-jf wants to merge 5 commits into
ehl-jf wants to merge 5 commits into
Conversation
Adds `jf api docs search <query>` as a subcommand of `jf api`, ranking operations from the embedded OpenAPI spec bundle (JGC-525) by a weighted contains/fuzzy match and printing a ready-to-run `jf api` one-liner for each. Fully offline, no server config required. Updates `jf api --ai-help` to recommend it before guessing at an unknown endpoint path.
Raises the fuzzy-fallback similarity floor from 0.4 to 0.6: whole-string Levenshtein similarity between unrelated but coincidentally similar-length words (e.g. "evidence" vs "environments", 0.42) was clearing the old bar, flooding results with false positives instead of the correct empty-result response. Adds JFROG_CLI_API_DOCS_SEARCH_FUZZY_MIN to override the floor for experimentation, defaulting to 0.6.
An agent that finds an operation via `jf api docs search` still had no way to know what payload a POST/PUT/PATCH call needs. The requestBody/ components.schemas data was already present in both the stub and full OpenAPI bundles, just unparsed. Extends apispec.Operation with a RequestBody (flattened top-level JSON schema properties, $ref-resolved one hop) and surfaces both Parameters and RequestBody in search results: JSON gains "parameters"/"request_body" fields, table view gains PARAMS/ BODY columns, and the "jf_api" one-liner now includes a minimal -d skeleton for required body fields.
jf api docs search exists primarily for agent consumption, so JSON is now always the default regardless of --ai-help/$JFROG_CLI_AI_HELP -- previously it only defaulted to JSON when agent-detected, table otherwise. --format table remains available for humans who want it.
Use http.MethodGet instead of the literal "GET", per CI's usestdlibvars linter.
Contributor
vitaliil-jfrog
approved these changes
Jul 10, 2026
christophermiJfrog
approved these changes
Jul 10, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
jf api docs search <query>as a subcommand ofjf api: a local, offline lookup over the OpenAPI operation catalog embedded by JGC-525 (docs/api-spec/), so an agent (or human) can find the right endpoint — and how to call it — before guessing atjf api <path>.Ranking: weighted contains-match across operationId/path/summary/tags, with a Levenshtein fuzzy fallback for typos, gated by a similarity floor (default
0.6, overridable via$JFROG_CLI_API_DOCS_SEARCH_FUZZY_MIN) to avoid coincidental false positives between unrelated words (e.g. "evidence" vs "environments").Payload awareness: extends
apispec.Operationto parserequestBody/components.schemas(already present in both the stub and full bundles, just previously unparsed). Matches now includeparametersandrequest_body(flattened top-level JSON schema fields — type, required, description, default), and thejf_apione-liner embeds a minimal-d '{...}'skeleton for required body fields — a match on its own wasn't enough to actually call the endpoint.Output: JSON by default (this command exists primarily for agent consumption);
--format tablefor humans. Empty results still reportspec_bundleso a caller knows a "stub" build may simply be missing the operation.Dispatch: added as
Subcommandson the existingapicommand, alongside its unchangedAction. One accepted, documented wrinkle: the bare, slash-less pathdocs(e.g.jf api docs) now routes to the new subcommand instead of an HTTP call; the realistic leading-slash form (jf api -X GET /docs) is unaffected, verified via a real-binary test against a mock server plus two permanent regression tests driving the actual urfave/cli dispatch logic.jf api --ai-helpnow recommendsjf api docs searchbefore guessing at an unknown endpoint.All tests have passed. New unit tests were added (
general/api/docs_search_test.go,docs/api-spec/parser_test.go,docs/api-spec/requestbody_test.go, two dispatch-regression tests ingeneral/api/cli_test.go) and pass locally; waiting on CI's platform-dependent integration tests before checking this box.The pull request is targeting the
masterbranch.The code has been validated to compile successfully by running
go vet ./....The code has been formatted properly using
go fmt ./....