feat: add qovery api spec command - #691
Merged
Merged
Conversation
Fetches and prints the Qovery OpenAPI spec (from Qovery/qovery-openapi-spec, the only stable source now that api-doc.qovery.com redirects to rendered docs instead of serving the raw file). Lets scripts and agents discover valid endpoints, methods, and request/response shapes before calling 'qovery api <endpoint>', instead of guessing or trusting a possibly stale copy. Requires no authentication. Added as a subcommand of the existing 'api' command rather than a new top-level command or a --spec flag, matching the parent-command-with-subcommands shape already used by 'auth'/'context'.
Contributor
There was a problem hiding this comment.
Pull request overview
Adds qovery api spec to fetch and print the live Qovery OpenAPI YAML, with optional file output.
Changes:
- Registers
specunderqovery api. - Fetches the GitHub-hosted specification with a timeout.
- Supports stdout output or
-o/--outputfile writing.
Suppressed comments (2)
cmd/api_spec.go:75
- When
-ois used, this status message is emitted to stdout viautils.PrintlnInfo(utils/printer.go:20-22), so stdout is not cleanly reserved for the spec/output stream. This breaks the documented “instead of stdout” mode for scripts that capture stdout; send the informational message to stderr or omit it.
utils.PrintlnInfo("OpenAPI spec written to " + apiSpecOutput)
cmd/api_spec.go:79
- The return value from
os.Stdout.Writeis discarded, so a partial or failed write (for example,ENOSPCon redirected output or a broken pipe) still makes the command exit successfully. Check the write error and return a non-zero status so callers can distinguish a complete spec from truncated output.
_, _ = os.Stdout.Write(body)
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
…t path Addresses Copilot review feedback on #691: the "written to" status message was going to stdout via PrintlnInfo, defeating the point of -o (a clean stream to script against); the direct os.Stdout.Write also discarded its error, so a broken pipe or full disk still exited 0.
benjaminch
approved these changes
Aug 25, 2026
Astach
reviewed
Aug 25, 2026
| if resp.StatusCode != http.StatusOK { | ||
| utils.PrintlnError(fmt.Errorf("failed to fetch OpenAPI spec: server returned %s", resp.Status)) | ||
| os.Exit(1) | ||
| panic("unreachable") // staticcheck false positive: https://staticcheck.io/docs/checks#SA5011 |
Contributor
There was a problem hiding this comment.
almost sure this isn't needed anymore.
Contributor
Author
There was a problem hiding this comment.
indeed. removed, thanks!
Astach
approved these changes
Aug 25, 2026
…spec.go That pattern only guards against SA5011 false positives where staticcheck can't prove code after os.Exit is unreachable and flags a later dereference as a possible nil access. None of the five os.Exit(1) calls here are followed by code that dereferences anything from the failed call, so there was nothing for staticcheck to misjudge. Verified by removing all five and confirming staticcheck, go vet, and go build stay clean.
4 tasks
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
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
qovery api spec, a subcommand of the existingqovery api— fetches and prints the Qovery OpenAPI spec (YAML), fromQovery/qovery-openapi-spec.-o/--output <file>writes the spec to a file instead of stdout.--specflag onapior a new top-levelqovery openapicommand:api <endpoint>always expects an endpoint argument and always makes a live authenticated call, so a flag with neither would mix two different mental models. A subcommand keepsapi <endpoint>completely unchanged and follows the same "parent command with its own default action + read-only subcommands" shape already used byauth(login vs.auth status/auth token) andcontext(show current context vs.context set).Motivation
There's no built-in way to discover valid endpoints/methods/schemas before calling
qovery api <endpoint>— today that means guessing, or trusting an external raw GitHub URL that a script/agent has to know about and that may be out of sync with the installed CLI.api-doc.qovery.comno longer serves the raw file either (it redirects to the rendered docs site), so the GitHub repo is the only stable source; this wraps that in the CLI directly.Test plan
go build ./...— cleangofmt -lon the changed file — cleanqovery api --help—speclisted as a subcommand, existingapi <endpoint>usage/examples unchangedqovery api spec— fetches and prints the live spec (31k lines of YAML)qovery api spec -o file.yaml— writes to fileqovery api organization(pre-existing passthrough) — still resolves and works, confirmingspecdoesn't shadow real endpoint callsraw.githubusercontent.com(rather than e.g. embedding/caching a copy pinned to the CLI's release) is the right tradeoff — this always reflects the live API surface but adds a network dependency and no offline fallback