From d9ec8d9a030505edcbd84d4e2486c839069cfb89 Mon Sep 17 00:00:00 2001 From: Jamie Pond Date: Tue, 17 Feb 2026 20:14:34 -0800 Subject: [PATCH 1/4] ok nice --- .gitignore | 1 + Makefile | 8 +- apps/web/app/docs/madea.config.tsx | 83 ++++++++++------- cli/scripts/gendocs.go | 8 +- docs/commands/yapi.md | 42 +++++++++ docs/commands/yapi_about.md | 32 +++++++ docs/commands/yapi_docs.md | 33 +++++++ docs/commands/yapi_history.md | 29 ++++++ docs/commands/yapi_import.md | 34 +++++++ docs/commands/yapi_list.md | 29 ++++++ docs/commands/yapi_lsp.md | 28 ++++++ docs/commands/yapi_run.md | 38 ++++++++ docs/commands/yapi_send.md | 45 ++++++++++ docs/commands/yapi_share.md | 28 ++++++ docs/commands/yapi_stress.md | 33 +++++++ docs/commands/yapi_test.md | 42 +++++++++ docs/commands/yapi_validate.md | 34 +++++++ docs/commands/yapi_version.md | 29 ++++++ docs/commands/yapi_watch.md | 31 +++++++ docs/topics/assert.md | 130 +++++++++++++++++++++++++++ docs/topics/chain.md | 112 +++++++++++++++++++++++ docs/topics/config.md | 140 +++++++++++++++++++++++++++++ docs/topics/environments.md | 101 +++++++++++++++++++++ docs/topics/jq.md | 86 ++++++++++++++++++ docs/topics/polling.md | 110 +++++++++++++++++++++++ docs/topics/protocols.md | 119 ++++++++++++++++++++++++ docs/topics/send.md | 84 +++++++++++++++++ docs/topics/testing.md | 124 +++++++++++++++++++++++++ docs/topics/variables.md | 109 ++++++++++++++++++++++ 29 files changed, 1683 insertions(+), 39 deletions(-) create mode 100644 docs/commands/yapi.md create mode 100644 docs/commands/yapi_about.md create mode 100644 docs/commands/yapi_docs.md create mode 100644 docs/commands/yapi_history.md create mode 100644 docs/commands/yapi_import.md create mode 100644 docs/commands/yapi_list.md create mode 100644 docs/commands/yapi_lsp.md create mode 100644 docs/commands/yapi_run.md create mode 100644 docs/commands/yapi_send.md create mode 100644 docs/commands/yapi_share.md create mode 100644 docs/commands/yapi_stress.md create mode 100644 docs/commands/yapi_test.md create mode 100644 docs/commands/yapi_validate.md create mode 100644 docs/commands/yapi_version.md create mode 100644 docs/commands/yapi_watch.md create mode 100644 docs/topics/assert.md create mode 100644 docs/topics/chain.md create mode 100644 docs/topics/config.md create mode 100644 docs/topics/environments.md create mode 100644 docs/topics/jq.md create mode 100644 docs/topics/polling.md create mode 100644 docs/topics/protocols.md create mode 100644 docs/topics/send.md create mode 100644 docs/topics/testing.md create mode 100644 docs/topics/variables.md diff --git a/.gitignore b/.gitignore index f1a380a9..45b757a3 100644 --- a/.gitignore +++ b/.gitignore @@ -54,6 +54,7 @@ dist apps/web/icons coverage.out cli/bin/yapi +cli/internal/docs/topics specs .specify .claude/commands/specify.* diff --git a/Makefile b/Makefile index a250f8ec..3ce5f7d3 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -.PHONY: build run run-print-analytics test fuzz fmt fmt-check clean install docker web web-run bump-patch bump-minor bump-major release build-all lint lint-install install-lint lint-quick lint-full gen-docs gh-action fuzz-cover local-release +.PHONY: build run run-print-analytics test fuzz fmt fmt-check clean install docker web web-run bump-patch bump-minor bump-major release build-all lint lint-install install-lint lint-quick lint-full gen-docs gh-action fuzz-cover local-release sync-docs NAME := yapi VERSION := $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev") @@ -45,7 +45,11 @@ lint-full: lint @echo "Running govulncheck..." @cd cli && govulncheck ./... -build: +sync-docs: + @mkdir -p cli/internal/docs/topics + @rsync -a --delete docs/topics/ cli/internal/docs/topics/ + +build: sync-docs @echo "Building yapi CLI..." @cd cli && go build -ldflags "$(LDFLAGS)" -o ./bin/yapi ./cmd/yapi @codesign --sign - --force ./cli/bin/yapi 2>/dev/null || true diff --git a/apps/web/app/docs/madea.config.tsx b/apps/web/app/docs/madea.config.tsx index e3710eec..febad95b 100644 --- a/apps/web/app/docs/madea.config.tsx +++ b/apps/web/app/docs/madea.config.tsx @@ -11,7 +11,6 @@ import Markdown from "react-markdown"; import remarkGfm from "remark-gfm"; import rehypeHighlight from "rehype-highlight"; import path from "path"; -import fs from "fs"; import { execSync } from "child_process"; // Get version info at build time (uses Vercel env vars, falls back to git for local dev) @@ -117,11 +116,11 @@ function ArticleView({ article }: ArticleViewProps) { } function extractDescription(content: string): string { - // Get the first non-empty line after the title (## heading) + // Get the first non-empty line after the title (# or ## heading) const lines = content.split('\n'); let foundTitle = false; for (const line of lines) { - if (line.startsWith('## ')) { + if (/^#{1,2}\s/.test(line)) { foundTitle = true; continue; } @@ -132,47 +131,69 @@ function extractDescription(content: string): string { return ''; } +function ArticleList({ articles }: { articles: FileInfo[] }) { + return ( +
+ {articles.map((article: FileInfo) => { + const description = extractDescription(article.content); + return ( + +

+ {article.title} +

+ {description && ( +

+ {description} +

+ )} + + ); + })} +
+ ); +} + function FileBrowserView({ articles }: FileBrowserViewProps) { + const topics = articles.filter((a) => a.path.startsWith("topics/")); + const commands = articles.filter((a) => a.path.startsWith("commands/")); + return (

- CLI Documentation + Documentation

- Auto-generated documentation for yapi CLI commands + Guides and command reference for the yapi CLI

{articles.length === 0 ? (
-

No docs yet. Run go run scripts/gendocs.go to generate.

+

No docs yet. Run make gen-docs to generate command reference.

) : ( -
- {articles.map((article: FileInfo) => { - const description = extractDescription(article.content); - return ( - -

- {article.title} -

- {description && ( -

- {description} -

- )} - - ); - })} +
+ {topics.length > 0 && ( +
+

Topics

+ +
+ )} + {commands.length > 0 && ( +
+

Commands

+ +
+ )}
)}
@@ -209,12 +230,8 @@ function LandingView() { ); } -const contentDir = path.join(process.cwd(), "app/_docs"); - -// Ensure directory exists for LocalFsDataProvider (which uses simple-git) -if (!fs.existsSync(contentDir)) { - fs.mkdirSync(contentDir, { recursive: true }); -} +// docs/ lives at repo root; web app is at apps/web/ +const contentDir = path.join(process.cwd(), "..", "..", "docs"); export const docsDataProvider = new LocalFsDataProvider({ contentDir, @@ -252,7 +269,7 @@ export async function generateDocsMetadata() { const config = createDocsConfig(); const metadata = await generateMetadataForIndex(config, { title: "CLI Documentation | yapi", - description: "Auto-generated documentation for yapi CLI commands", + description: "Guides and command reference for the yapi CLI", }); return { ...metadata, diff --git a/cli/scripts/gendocs.go b/cli/scripts/gendocs.go index 560d19fe..dfc7fd51 100644 --- a/cli/scripts/gendocs.go +++ b/cli/scripts/gendocs.go @@ -12,15 +12,15 @@ import ( ) func main() { - outputDir := "../apps/web/app/_docs" + outputDir := "../docs/commands" if len(os.Args) > 1 { outputDir = os.Args[1] } - // Verify the parent path exists (apps/web/app) - fail fast if structure is wrong - parentDir := strings.TrimSuffix(outputDir, "/_docs") + // Verify the parent path exists (docs/) - fail fast if structure is wrong + parentDir := strings.TrimSuffix(outputDir, "/commands") if _, err := os.Stat(parentDir); os.IsNotExist(err) { - log.Fatalf("web app not found at %s - did the directory structure change?", parentDir) + log.Fatalf("docs directory not found at %s - did the directory structure change?", parentDir) } if err := os.MkdirAll(outputDir, 0755); err != nil { diff --git a/docs/commands/yapi.md b/docs/commands/yapi.md new file mode 100644 index 00000000..fd09e073 --- /dev/null +++ b/docs/commands/yapi.md @@ -0,0 +1,42 @@ +## yapi + +yapi is a unified API client for HTTP, gRPC, and TCP + +### Synopsis + +yapi is a unified API client for HTTP, gRPC, GraphQL, and TCP. + +Run 'yapi docs' to browse topic-based documentation. + +``` +yapi [flags] +``` + +### Options + +``` + --binary-output Display binary content to stdout (by default binary content is hidden) + -h, --help help for yapi + --insecure Skip TLS verification for HTTPS requests; use insecure transport for gRPC + --no-color Disable color output + -u, --url string Override the URL specified in the config file +``` + +### SEE ALSO + +* [yapi about](yapi_about) - Show comprehensive yapi developer guide +* [yapi docs](yapi_docs) - Browse topic-based documentation +* [yapi history](yapi_history) - Show yapi command history (default: last 10) +* [yapi import](yapi_import) - Import an external collection (Postman) to yapi format +* [yapi list](yapi_list) - List all yapi config files in the current directory or project +* [yapi lsp](yapi_lsp) - Run the yapi language server over stdio +* [yapi run](yapi_run) - Run a request defined in a yapi config file (reads from stdin if no file specified) +* [yapi send](yapi_send) - Send a quick request without a config file +* [yapi share](yapi_share) - Generate a shareable yapi.run link for a config file +* [yapi stress](yapi_stress) - Load test a yapi config file with concurrent requests +* [yapi test](yapi_test) - Run all *.test.yapi, *.test.yapi.yml, *.test.yapi.yaml files in the current directory or specified directory +* [yapi validate](yapi_validate) - Validate a yapi config file +* [yapi version](yapi_version) - Print version information +* [yapi watch](yapi_watch) - Watch a yapi config file and re-run on changes + +###### Auto generated by spf13/cobra on 17-Feb-2026 diff --git a/docs/commands/yapi_about.md b/docs/commands/yapi_about.md new file mode 100644 index 00000000..631a2ad6 --- /dev/null +++ b/docs/commands/yapi_about.md @@ -0,0 +1,32 @@ +## yapi about + +Show comprehensive yapi developer guide + +### Synopsis + +Display a comprehensive developer guide for working with yapi. Includes syntax, examples, best practices, and project organization patterns. + +``` +yapi about [flags] +``` + +### Options + +``` + -h, --help help for about +``` + +### Options inherited from parent commands + +``` + --binary-output Display binary content to stdout (by default binary content is hidden) + --insecure Skip TLS verification for HTTPS requests; use insecure transport for gRPC + --no-color Disable color output + -u, --url string Override the URL specified in the config file +``` + +### SEE ALSO + +* [yapi](yapi) - yapi is a unified API client for HTTP, gRPC, and TCP + +###### Auto generated by spf13/cobra on 17-Feb-2026 diff --git a/docs/commands/yapi_docs.md b/docs/commands/yapi_docs.md new file mode 100644 index 00000000..972876a3 --- /dev/null +++ b/docs/commands/yapi_docs.md @@ -0,0 +1,33 @@ +## yapi docs + +Browse topic-based documentation + +### Synopsis + +Browse topic-based documentation for yapi features. +Run 'yapi docs' to see all topics, or 'yapi docs ' to read one. + +``` +yapi docs [topic] [flags] +``` + +### Options + +``` + -h, --help help for docs +``` + +### Options inherited from parent commands + +``` + --binary-output Display binary content to stdout (by default binary content is hidden) + --insecure Skip TLS verification for HTTPS requests; use insecure transport for gRPC + --no-color Disable color output + -u, --url string Override the URL specified in the config file +``` + +### SEE ALSO + +* [yapi](yapi) - yapi is a unified API client for HTTP, gRPC, and TCP + +###### Auto generated by spf13/cobra on 17-Feb-2026 diff --git a/docs/commands/yapi_history.md b/docs/commands/yapi_history.md new file mode 100644 index 00000000..a2172935 --- /dev/null +++ b/docs/commands/yapi_history.md @@ -0,0 +1,29 @@ +## yapi history + +Show yapi command history (default: last 10) + +``` +yapi history [count] [flags] +``` + +### Options + +``` + -h, --help help for history + --json Output as JSON +``` + +### Options inherited from parent commands + +``` + --binary-output Display binary content to stdout (by default binary content is hidden) + --insecure Skip TLS verification for HTTPS requests; use insecure transport for gRPC + --no-color Disable color output + -u, --url string Override the URL specified in the config file +``` + +### SEE ALSO + +* [yapi](yapi) - yapi is a unified API client for HTTP, gRPC, and TCP + +###### Auto generated by spf13/cobra on 17-Feb-2026 diff --git a/docs/commands/yapi_import.md b/docs/commands/yapi_import.md new file mode 100644 index 00000000..038e9c23 --- /dev/null +++ b/docs/commands/yapi_import.md @@ -0,0 +1,34 @@ +## yapi import + +Import an external collection (Postman) to yapi format + +### Synopsis + +Import a Postman collection JSON file and convert it to yapi YAML files. Creates a directory structure mirroring the collection's folder organization. + +``` +yapi import [file] [flags] +``` + +### Options + +``` + -e, --env string Postman environment file (.json) to import variables from + -h, --help help for import + -o, --output string Directory to save imported yapi files (default "./imported") +``` + +### Options inherited from parent commands + +``` + --binary-output Display binary content to stdout (by default binary content is hidden) + --insecure Skip TLS verification for HTTPS requests; use insecure transport for gRPC + --no-color Disable color output + -u, --url string Override the URL specified in the config file +``` + +### SEE ALSO + +* [yapi](yapi) - yapi is a unified API client for HTTP, gRPC, and TCP + +###### Auto generated by spf13/cobra on 17-Feb-2026 diff --git a/docs/commands/yapi_list.md b/docs/commands/yapi_list.md new file mode 100644 index 00000000..af9d237a --- /dev/null +++ b/docs/commands/yapi_list.md @@ -0,0 +1,29 @@ +## yapi list + +List all yapi config files in the current directory or project + +``` +yapi list [directory] [flags] +``` + +### Options + +``` + -h, --help help for list + --json Output as JSON +``` + +### Options inherited from parent commands + +``` + --binary-output Display binary content to stdout (by default binary content is hidden) + --insecure Skip TLS verification for HTTPS requests; use insecure transport for gRPC + --no-color Disable color output + -u, --url string Override the URL specified in the config file +``` + +### SEE ALSO + +* [yapi](yapi) - yapi is a unified API client for HTTP, gRPC, and TCP + +###### Auto generated by spf13/cobra on 17-Feb-2026 diff --git a/docs/commands/yapi_lsp.md b/docs/commands/yapi_lsp.md new file mode 100644 index 00000000..757ddcfb --- /dev/null +++ b/docs/commands/yapi_lsp.md @@ -0,0 +1,28 @@ +## yapi lsp + +Run the yapi language server over stdio + +``` +yapi lsp [flags] +``` + +### Options + +``` + -h, --help help for lsp +``` + +### Options inherited from parent commands + +``` + --binary-output Display binary content to stdout (by default binary content is hidden) + --insecure Skip TLS verification for HTTPS requests; use insecure transport for gRPC + --no-color Disable color output + -u, --url string Override the URL specified in the config file +``` + +### SEE ALSO + +* [yapi](yapi) - yapi is a unified API client for HTTP, gRPC, and TCP + +###### Auto generated by spf13/cobra on 17-Feb-2026 diff --git a/docs/commands/yapi_run.md b/docs/commands/yapi_run.md new file mode 100644 index 00000000..cff9a728 --- /dev/null +++ b/docs/commands/yapi_run.md @@ -0,0 +1,38 @@ +## yapi run + +Run a request defined in a yapi config file (reads from stdin if no file specified) + +### Synopsis + +Run a request defined in a yapi config file (reads from stdin if no file specified). + +Related: yapi docs assert, yapi docs chain, yapi docs variables + +``` +yapi run [file] [flags] +``` + +### Options + +``` + -e, --env string Target environment from yapi.config.yml + -h, --help help for run + --json Output result as JSON with full metadata + --strict-env Strict env mode: error on missing env files, no OS env fallback + -v, --verbose Show verbose output (request details, timing, headers) +``` + +### Options inherited from parent commands + +``` + --binary-output Display binary content to stdout (by default binary content is hidden) + --insecure Skip TLS verification for HTTPS requests; use insecure transport for gRPC + --no-color Disable color output + -u, --url string Override the URL specified in the config file +``` + +### SEE ALSO + +* [yapi](yapi) - yapi is a unified API client for HTTP, gRPC, and TCP + +###### Auto generated by spf13/cobra on 17-Feb-2026 diff --git a/docs/commands/yapi_send.md b/docs/commands/yapi_send.md new file mode 100644 index 00000000..5b207383 --- /dev/null +++ b/docs/commands/yapi_send.md @@ -0,0 +1,45 @@ +## yapi send + +Send a quick request without a config file + +### Synopsis + +Send a one-off HTTP or TCP request directly from the command line. +The transport is auto-detected from the URL scheme (tcp://, grpc://, or HTTP by default). + +Examples: + yapi send https://httpbin.org/get + yapi send -X POST https://httpbin.org/post '{"hello":"world"}' + yapi send tcp://localhost:9877 '{"type":"health","params":{}}' + +Related: yapi docs send, yapi docs protocols + +``` +yapi send [body] [flags] +``` + +### Options + +``` + -H, --header strings Custom headers (e.g. -H 'Content-Type: application/json') + -h, --help help for send + --jq string JQ filter to apply to the response + --json Output result as JSON with full metadata + -X, --method string HTTP method (default: GET, or POST if body is provided) + -v, --verbose Show verbose output (request details, timing, headers) +``` + +### Options inherited from parent commands + +``` + --binary-output Display binary content to stdout (by default binary content is hidden) + --insecure Skip TLS verification for HTTPS requests; use insecure transport for gRPC + --no-color Disable color output + -u, --url string Override the URL specified in the config file +``` + +### SEE ALSO + +* [yapi](yapi) - yapi is a unified API client for HTTP, gRPC, and TCP + +###### Auto generated by spf13/cobra on 17-Feb-2026 diff --git a/docs/commands/yapi_share.md b/docs/commands/yapi_share.md new file mode 100644 index 00000000..d57ae19e --- /dev/null +++ b/docs/commands/yapi_share.md @@ -0,0 +1,28 @@ +## yapi share + +Generate a shareable yapi.run link for a config file + +``` +yapi share [file] [flags] +``` + +### Options + +``` + -h, --help help for share +``` + +### Options inherited from parent commands + +``` + --binary-output Display binary content to stdout (by default binary content is hidden) + --insecure Skip TLS verification for HTTPS requests; use insecure transport for gRPC + --no-color Disable color output + -u, --url string Override the URL specified in the config file +``` + +### SEE ALSO + +* [yapi](yapi) - yapi is a unified API client for HTTP, gRPC, and TCP + +###### Auto generated by spf13/cobra on 17-Feb-2026 diff --git a/docs/commands/yapi_stress.md b/docs/commands/yapi_stress.md new file mode 100644 index 00000000..70ccb95e --- /dev/null +++ b/docs/commands/yapi_stress.md @@ -0,0 +1,33 @@ +## yapi stress + +Load test a yapi config file with concurrent requests + +``` +yapi stress [file] [flags] +``` + +### Options + +``` + -d, --duration string Duration to run test (e.g., 10s, 1m) - overrides num-requests + -e, --env string Target environment from yapi.config.yml + -h, --help help for stress + -n, --num-requests int Total number of requests to make (default 100) + -p, --parallel int Number of concurrent requests (default 1) + -y, --yes Skip confirmation prompt +``` + +### Options inherited from parent commands + +``` + --binary-output Display binary content to stdout (by default binary content is hidden) + --insecure Skip TLS verification for HTTPS requests; use insecure transport for gRPC + --no-color Disable color output + -u, --url string Override the URL specified in the config file +``` + +### SEE ALSO + +* [yapi](yapi) - yapi is a unified API client for HTTP, gRPC, and TCP + +###### Auto generated by spf13/cobra on 17-Feb-2026 diff --git a/docs/commands/yapi_test.md b/docs/commands/yapi_test.md new file mode 100644 index 00000000..37656ccf --- /dev/null +++ b/docs/commands/yapi_test.md @@ -0,0 +1,42 @@ +## yapi test + +Run all *.test.yapi, *.test.yapi.yml, *.test.yapi.yaml files in the current directory or specified directory + +### Synopsis + +Run all *.test.yapi, *.test.yapi.yml, *.test.yapi.yaml files in the current directory or specified directory. + +Related: yapi docs testing, yapi docs assert + +``` +yapi test [directory] [flags] +``` + +### Options + +``` + -a, --all Run all *.yapi, *.yapi.yml, *.yapi.yaml files (not just test files) + -e, --env string Target environment from yapi.config.yml + -h, --help help for test + --no-start Skip starting the dev server (even if configured in yapi.config.yml) + -p, --parallel int Number of parallel threads to run tests on (default 1) + --start string Command to start the dev server (overrides yapi.config.yml) + -v, --verbose Show verbose output for each test + --wait-on strings URL(s) to wait for before running tests (http://, grpc://, tcp://) + --wait-timeout duration Health check timeout (default 1m0s) +``` + +### Options inherited from parent commands + +``` + --binary-output Display binary content to stdout (by default binary content is hidden) + --insecure Skip TLS verification for HTTPS requests; use insecure transport for gRPC + --no-color Disable color output + -u, --url string Override the URL specified in the config file +``` + +### SEE ALSO + +* [yapi](yapi) - yapi is a unified API client for HTTP, gRPC, and TCP + +###### Auto generated by spf13/cobra on 17-Feb-2026 diff --git a/docs/commands/yapi_validate.md b/docs/commands/yapi_validate.md new file mode 100644 index 00000000..b32c7bd9 --- /dev/null +++ b/docs/commands/yapi_validate.md @@ -0,0 +1,34 @@ +## yapi validate + +Validate a yapi config file + +### Synopsis + +Validate a yapi config file and report diagnostics. Use - to read from stdin. + +``` +yapi validate [file] [flags] +``` + +### Options + +``` + -a, --all Validate all *.yapi, *.yapi.yml, *.yapi.yaml files in current directory or specified directory + -h, --help help for validate + --json Output diagnostics as JSON +``` + +### Options inherited from parent commands + +``` + --binary-output Display binary content to stdout (by default binary content is hidden) + --insecure Skip TLS verification for HTTPS requests; use insecure transport for gRPC + --no-color Disable color output + -u, --url string Override the URL specified in the config file +``` + +### SEE ALSO + +* [yapi](yapi) - yapi is a unified API client for HTTP, gRPC, and TCP + +###### Auto generated by spf13/cobra on 17-Feb-2026 diff --git a/docs/commands/yapi_version.md b/docs/commands/yapi_version.md new file mode 100644 index 00000000..af563851 --- /dev/null +++ b/docs/commands/yapi_version.md @@ -0,0 +1,29 @@ +## yapi version + +Print version information + +``` +yapi version [flags] +``` + +### Options + +``` + -h, --help help for version + --json Output version info as JSON +``` + +### Options inherited from parent commands + +``` + --binary-output Display binary content to stdout (by default binary content is hidden) + --insecure Skip TLS verification for HTTPS requests; use insecure transport for gRPC + --no-color Disable color output + -u, --url string Override the URL specified in the config file +``` + +### SEE ALSO + +* [yapi](yapi) - yapi is a unified API client for HTTP, gRPC, and TCP + +###### Auto generated by spf13/cobra on 17-Feb-2026 diff --git a/docs/commands/yapi_watch.md b/docs/commands/yapi_watch.md new file mode 100644 index 00000000..f31f1768 --- /dev/null +++ b/docs/commands/yapi_watch.md @@ -0,0 +1,31 @@ +## yapi watch + +Watch a yapi config file and re-run on changes + +``` +yapi watch [file] [flags] +``` + +### Options + +``` + -e, --env string Target environment from yapi.config.yml + -h, --help help for watch + --no-pretty Disable pretty TUI mode + -p, --pretty Enable pretty TUI mode +``` + +### Options inherited from parent commands + +``` + --binary-output Display binary content to stdout (by default binary content is hidden) + --insecure Skip TLS verification for HTTPS requests; use insecure transport for gRPC + --no-color Disable color output + -u, --url string Override the URL specified in the config file +``` + +### SEE ALSO + +* [yapi](yapi) - yapi is a unified API client for HTTP, gRPC, and TCP + +###### Auto generated by spf13/cobra on 17-Feb-2026 diff --git a/docs/topics/assert.md b/docs/topics/assert.md new file mode 100644 index 00000000..98ee788f --- /dev/null +++ b/docs/topics/assert.md @@ -0,0 +1,130 @@ +# Assertions + +Assertions let you validate HTTP responses — status codes, body content, and headers. +They're the core of yapi's testing capability. + +## Status Expectations + +```yaml +expect: + status: 200 # Exact match + status: [200, 201, 204] # Any of these +``` + +## Body Assertions + +Body assertions are JQ expressions that must evaluate to `true`: + +```yaml +expect: + status: 200 + assert: + - .id != null + - .email != null + - .active == true +``` + +### Operators + +All JQ comparison operators work: `==`, `!=`, `>`, `>=`, `<`, `<=` + +```yaml +assert: + - . | length > 0 # Array has items + - .count >= 10 # Numeric comparison + - .name != "" # Not empty string +``` + +### Array Operations + +```yaml +assert: + - . | type == "array" + - . | length > 0 + - .[0].name != null # First element + - .[] | .status == "active" # All items match +``` + +### Type Checks + +```yaml +assert: + - . | type == "array" + - .data | type == "object" + - .count | type == "number" +``` + +## Environment Variable References + +Compare response values against environment variables using `env.VAR_NAME`: + +```yaml +assert: + - .owner.login == env.GITHUB_USER + - .email == env.EXPECTED_EMAIL +``` + +## Header Assertions + +Use the grouped syntax to assert on response headers: + +```yaml +expect: + status: 200 + assert: + headers: + - .["content-type"] | startswith("application/json") + - .["x-request-id"] != null + body: + - .id != null +``` + +When using the grouped syntax, body assertions go under `body:`. + +## Flat vs Grouped Syntax + +**Flat** (all assertions are body assertions): +```yaml +assert: + - .id != null +``` + +**Grouped** (separate body and header assertions): +```yaml +assert: + headers: + - .["content-type"] | contains("json") + body: + - .id != null +``` + +## Assertions in Chains + +Each chain step can have its own `expect` block: + +```yaml +chain: + - name: create + url: /api/items + method: POST + body: { title: "test" } + expect: + status: 201 + assert: + - .id != null + + - name: verify + url: /api/items/${create.id} + method: GET + expect: + status: 200 + assert: + - .title == "test" +``` + +## See Also + +- `yapi docs chain` — Multi-step request chaining +- `yapi docs jq` — JQ filtering and expressions +- `yapi docs variables` — Variable interpolation +- `yapi docs testing` — Test runner and CI/CD diff --git a/docs/topics/chain.md b/docs/topics/chain.md new file mode 100644 index 00000000..0ba67324 --- /dev/null +++ b/docs/topics/chain.md @@ -0,0 +1,112 @@ +# Request Chaining + +Chains let you execute multiple requests sequentially, passing data between steps. +Login, use the token, verify the result — all in one file. + +## Basic Chain + +```yaml +yapi: v1 +chain: + - name: login + url: https://api.example.com/auth/login + method: POST + body: + username: ${USERNAME} + password: ${PASSWORD} + expect: + status: 200 + assert: + - .token != null + + - name: get_profile + url: https://api.example.com/me + method: GET + headers: + Authorization: Bearer ${login.token} + expect: + status: 200 +``` + +## Step References + +Reference data from previous steps with `${step_name.field}`: + +```yaml +- name: create_user + url: /api/users + method: POST + body: { name: "Alice" } + expect: + assert: + - .id != null + +- name: get_user + url: /api/users/${create_user.id} + method: GET +``` + +### Nested Paths + +Access nested JSON fields with dot notation: + +```yaml +${step_name.data.user.email} # Nested object +${step_name.items[0].id} # Array indexing +``` + +### Where References Work + +Step references work in any string field: URLs, headers, body values, assertions. + +```yaml +- name: verify + url: /api/users/${create.id} + headers: + Authorization: Bearer ${login.token} + expect: + assert: + - .email == env.EXPECTED_EMAIL +``` + +## Type Preservation + +When a `${ref}` is the entire value (not part of a larger string), its type is preserved: + +```yaml +body: + user_id: ${get_user.id} # Stays an integer + name: "User ${get_user.id}" # String interpolation +``` + +## Fail-Fast Behavior + +Chains stop on the first failure: +- If a request fails (network error, timeout), the chain stops +- If an assertion fails, the chain stops +- Subsequent steps are skipped + +## Step Config Inheritance + +Each step can override any base-level config field. Steps inherit from the +top-level config (URL, headers, timeout, etc.): + +```yaml +yapi: v1 +timeout: 10s # Default for all steps + +chain: + - name: fast_check + url: /health + timeout: 2s # Override for this step + + - name: slow_op + url: /process + timeout: 30s # Override for this step +``` + +## See Also + +- `yapi docs assert` — Assertions on status, body, and headers +- `yapi docs variables` — Variable interpolation and resolution +- `yapi docs polling` — Polling with wait_for diff --git a/docs/topics/config.md b/docs/topics/config.md new file mode 100644 index 00000000..1b769786 --- /dev/null +++ b/docs/topics/config.md @@ -0,0 +1,140 @@ +# Config Reference + +Every yapi request file starts with `yapi: v1`. This page lists all available fields. + +## Project Layout + +Place a `yapi.config.yml` at your project root to define environments and base URLs. Request files (`.yapi.yml`) can live anywhere beneath it — yapi walks up the directory tree to find the nearest config. + +``` +my-project/ +├── yapi.config.yml # project config (environments, base URLs) +└── yapi/ + ├── homepage.yapi.yml # GET / + ├── sitemap.yapi.yml # GET /sitemap.xml + └── health.yapi.yml # GET /healthz +``` + +### Example: `yapi.config.yml` + +```yaml +yapi: v1 + +default_environment: local + +environments: + local: + url: http://localhost:3000 + prod: + url: https://api.example.com +``` + +### Example: `yapi/homepage.yapi.yml` + +```yaml +yapi: v1 +path: / +method: GET + +headers: + User-Agent: yapi-cli + +expect: + status: 200 +``` + +Because the request file uses `path: /` instead of a full `url`, yapi resolves it against the active environment's base URL. Running `yapi run yapi/homepage.yapi.yml` hits `http://localhost:3000/` by default, or `https://api.example.com/` with `-e prod`. + +## Request Fields + +| Field | Type | Description | +|---|---|---| +| `yapi` | string | **Required.** Version tag. Always `v1`. | +| `url` | string | Full request URL | +| `path` | string | Path appended to environment base URL | +| `method` | string | HTTP method: GET, POST, PUT, PATCH, DELETE | +| `headers` | map | Request headers | +| `query` | map | Query parameters | +| `timeout` | string | Request timeout (e.g., `"4s"`, `"100ms"`) | +| `delay` | string | Wait before executing (e.g., `"5s"`) | +| `insecure` | bool | Skip TLS verification | + +`url` and `path` are mutually exclusive. Use `path` when `yapi.config.yml` provides a base URL. + +## Body Fields + +These are mutually exclusive — use only one: + +| Field | Type | Description | +|---|---|---| +| `body` | map | JSON object body | +| `json` | string | Raw JSON string body | +| `form` | map | Form-encoded body | + +## Response Processing + +| Field | Type | Description | +|---|---|---| +| `jq_filter` | string | JQ expression to transform response | +| `output_file` | string | Save response body to file | +| `content_type` | string | Override content type | + +## GraphQL Fields + +| Field | Type | Description | +|---|---|---| +| `graphql` | string | GraphQL query or mutation | +| `variables` | map | GraphQL variables | + +## gRPC Fields + +| Field | Type | Description | +|---|---|---| +| `service` | string | gRPC service name | +| `rpc` | string | RPC method name | +| `proto` | string | Path to .proto file | +| `proto_path` | string | Proto import path | +| `plaintext` | bool | No TLS for gRPC | + +## TCP Fields + +| Field | Type | Description | +|---|---|---| +| `data` | string | Raw data to send | +| `encoding` | string | `text` (default), `hex`, `base64` | +| `read_timeout` | int | Seconds to wait for response | +| `idle_timeout` | int | Milliseconds before response is considered complete | +| `close_after_send` | bool | Close connection after sending | + +## Testing Fields + +| Field | Type | Description | +|---|---|---| +| `expect` | object | Status and assertion expectations | +| `expect.status` | int/[]int | Expected status code(s) | +| `expect.assert` | list/map | Body and header assertions | +| `wait_for` | object | Polling configuration | +| `chain` | list | Multi-step request chain | + +## Environment Fields + +| Field | Type | Description | +|---|---|---| +| `env_files` | []string | Paths to .env files to load | + +## Project Config (`yapi.config.yml`) + +| Field | Type | Description | +|---|---|---| +| `default_environment` | string | Environment used without `-e` | +| `defaults.vars` | map | Variables for all environments | +| `environments` | map | Environment definitions | +| `environments.{name}.url` | string | Base URL | +| `environments.{name}.vars` | map | Environment-specific variables | +| `environments.{name}.env_file` | string | .env file path | + +## See Also + +- `yapi docs protocols` — Protocol-specific details and examples +- `yapi docs variables` — Variable interpolation +- `yapi docs assert` — Assertion syntax diff --git a/docs/topics/environments.md b/docs/topics/environments.md new file mode 100644 index 00000000..162aa5db --- /dev/null +++ b/docs/topics/environments.md @@ -0,0 +1,101 @@ +# Environments + +Environments let you switch between local, staging, and production configs +without changing your request files. + +## Project Config File + +Create `yapi.config.yml` in your project root: + +```yaml +yapi: v1 + +default_environment: local + +defaults: + vars: + API_VERSION: v1 + SHARED_VAR: shared_value + +environments: + local: + url: http://localhost:3000 + vars: + API_KEY: dev_key + DEBUG: "true" + + staging: + url: https://staging.api.example.com + vars: + API_KEY: ${STAGING_API_KEY} + + prod: + url: https://api.example.com + vars: + API_KEY: ${PROD_API_KEY} + env_file: .env.prod +``` + +## Key Fields + +- **`default_environment`**: Used when `-e` flag is not specified +- **`defaults`**: Variables available in ALL environments +- **`environments`**: Environment-specific settings + - **`url`**: Base URL for requests using `path:` instead of `url:` + - **`vars`**: Environment-specific variables + - **`env_file`**: Path to a `.env` file to load + +## Selecting an Environment + +```bash +yapi run request.yapi.yml -e staging +yapi test ./tests -e prod +``` + +Without `-e`, the `default_environment` is used. + +## How URL Resolution Works + +Request files can use `path:` instead of `url:`: + +```yaml +# request.yapi.yml +yapi: v1 +path: /api/users +method: GET +``` + +The `path` is appended to the environment's `url`. So with `-e local`, +the full URL becomes `http://localhost:3000/api/users`. + +## Variable Precedence + +When the same variable is defined in multiple places: + +1. Chain step references (highest priority) +2. Environment-specific `vars` +3. `defaults.vars` +4. Shell environment variables +5. Default values (`${VAR:-default}`) + +## Env Files + +Load secrets from `.env` files per environment: + +```yaml +environments: + prod: + env_file: .env.prod +``` + +``` +# .env.prod +API_KEY=sk-prod-abc123 +DB_URL=postgres://prod-host/db +``` + +## See Also + +- `yapi docs variables` — Variable interpolation and resolution +- `yapi docs config` — Full YAML config field reference +- `yapi docs testing` — Running tests across environments diff --git a/docs/topics/jq.md b/docs/topics/jq.md new file mode 100644 index 00000000..7abee7b7 --- /dev/null +++ b/docs/topics/jq.md @@ -0,0 +1,86 @@ +# JQ Filtering + +JQ lets you filter and transform JSON responses inline — +both for display (`jq_filter`) and for validation (`assert`). + +## Response Filtering + +Use `jq_filter` to transform what gets displayed: + +```yaml +yapi: v1 +url: https://api.example.com/users +method: GET +jq_filter: '[.[] | {name, email}] | sort_by(.name)' +``` + +This filters the response before printing, so you only see what matters. + +## JQ in Assertions + +Assertions are JQ expressions that must evaluate to `true`: + +```yaml +expect: + assert: + - .id != null + - . | length > 0 + - .data | type == "object" + - .[0].name | startswith("A") +``` + +## Common Patterns + +### Check array length +```yaml +assert: + - . | length > 0 + - .items | length == 10 +``` + +### Check type +```yaml +assert: + - . | type == "array" + - .data | type == "object" + - .count | type == "number" +``` + +### String operations +```yaml +assert: + - .name | startswith("test_") + - .email | endswith("@example.com") + - .url | contains("api") +``` + +### Check all items in array +```yaml +assert: + - .[] | .status == "active" # Every item matches + - [.[] | .score > 0] | all # All scores positive +``` + +### Select specific fields +```yaml +jq_filter: '{id, name, email}' # Single object +jq_filter: '[.[] | {id, name}]' # Array of objects +``` + +### Sort and limit +```yaml +jq_filter: 'sort_by(.created_at) | reverse | .[:5]' +``` + +## JQ with yapi send + +Apply JQ filters on the command line: + +```bash +yapi send https://api.example.com/users --jq '.[0].name' +``` + +## See Also + +- `yapi docs assert` — Assertions on status, body, and headers +- `yapi docs send` — Quick one-off requests with --jq flag diff --git a/docs/topics/polling.md b/docs/topics/polling.md new file mode 100644 index 00000000..6e770862 --- /dev/null +++ b/docs/topics/polling.md @@ -0,0 +1,110 @@ +# Polling + +The `wait_for` block lets you poll an endpoint until conditions are met. +Useful for async operations, health checks, and eventual consistency. + +## Basic Polling + +```yaml +yapi: v1 +url: https://api.example.com/jobs/123 +method: GET + +wait_for: + until: + - .status == "completed" + period: 2s + timeout: 30s +``` + +This sends GET requests every 2 seconds until `.status == "completed"` or 30 seconds elapse. + +## Fields + +- **`until`**: Array of JQ assertions. ALL must pass to stop polling. +- **`period`**: Fixed delay between attempts (e.g., `"1s"`, `"500ms"`). +- **`backoff`**: Exponential backoff (mutually exclusive with `period`). +- **`timeout`**: Maximum wait time. Default: `30s`. + +## Fixed Period + +Retry at a constant interval: + +```yaml +wait_for: + until: + - .ready == true + period: 1s + timeout: 60s +``` + +## Exponential Backoff + +Start with a short delay, grow exponentially: + +```yaml +wait_for: + until: + - .status == "done" + backoff: + seed: 1s # First wait: 1s + multiplier: 2 # Then 2s, 4s, 8s, 16s... + timeout: 60s +``` + +The delay doubles each attempt: seed, seed*multiplier, seed*multiplier^2, etc. +`multiplier` must be greater than 1. + +## Multiple Conditions + +All `until` conditions must pass simultaneously: + +```yaml +wait_for: + until: + - .status == "completed" + - .result != null + - .errors | length == 0 + period: 2s + timeout: 30s +``` + +## Polling in Chains + +Each chain step can have its own `wait_for`: + +```yaml +chain: + - name: start_job + url: /api/jobs + method: POST + body: { task: "process" } + expect: + status: 202 + assert: + - .job_id != null + + - name: wait_done + url: /api/jobs/${start_job.job_id} + method: GET + wait_for: + until: + - .status == "completed" + period: 2s + timeout: 60s + expect: + assert: + - .result != null +``` + +## Behavior + +- If the request itself fails (network error), polling continues until timeout +- If assertions don't pass, polling retries +- On timeout, the test fails with an error +- On success, execution continues normally (chain proceeds to next step) + +## See Also + +- `yapi docs assert` — Assertions used in until conditions +- `yapi docs chain` — Multi-step request chaining diff --git a/docs/topics/protocols.md b/docs/topics/protocols.md new file mode 100644 index 00000000..5f28c22c --- /dev/null +++ b/docs/topics/protocols.md @@ -0,0 +1,119 @@ +# Protocols + +yapi supports HTTP, gRPC, GraphQL, and TCP as first-class protocols. +Transport is detected from the URL scheme and config fields. + +## HTTP / REST + +The default protocol. Standard request/response: + +```yaml +yapi: v1 +url: https://api.example.com/users +method: POST +content_type: application/json +headers: + Authorization: Bearer ${TOKEN} +body: + name: "Alice" + email: "alice@example.com" +expect: + status: 201 +``` + +### Form Data + +```yaml +yapi: v1 +url: https://example.com/login +method: POST +form: + username: admin + password: ${PASSWORD} +``` + +## GraphQL + +Detected by the `graphql:` field: + +```yaml +yapi: v1 +url: https://countries.trevorblades.com/graphql + +graphql: | + query getCountry($code: ID!) { + country(code: $code) { + name + capital + } + } + +variables: + code: "US" +``` + +GraphQL requests are always POST. The `graphql` field contains your query or mutation, +and `variables` holds the GraphQL variables. + +## gRPC + +Detected by `grpc://` URL scheme. Requires server reflection or proto files: + +```yaml +yapi: v1 +url: grpc://localhost:50051 +service: helloworld.Greeter +rpc: SayHello + +body: + name: "World" +``` + +### With Proto Files + +```yaml +yapi: v1 +url: grpc://localhost:50051 +service: helloworld.Greeter +rpc: SayHello +proto: ./proto/helloworld.proto +proto_path: ./proto + +body: + name: "World" +``` + +### Insecure / Plaintext + +```yaml +plaintext: true # No TLS +insecure: true # Skip TLS verification +``` + +## TCP + +Detected by `tcp://` URL scheme. Raw socket communication: + +```yaml +yapi: v1 +url: tcp://localhost:9877 +data: '{"type":"health","params":{}}' +encoding: text # text (default), hex, base64 +read_timeout: 5 # Seconds to wait for response +idle_timeout: 500 # Milliseconds before considering response complete +close_after_send: false # Keep connection open to read response +``` + +## Auto-Detection Summary + +| Indicator | Protocol | +|---|---| +| `grpc://` URL | gRPC | +| `tcp://` URL | TCP | +| `graphql:` field present | GraphQL | +| Everything else | HTTP | + +## See Also + +- `yapi docs send` — Quick one-off requests (auto-detects protocol) +- `yapi docs config` — Full field reference for all protocols diff --git a/docs/topics/send.md b/docs/topics/send.md new file mode 100644 index 00000000..cd17af0c --- /dev/null +++ b/docs/topics/send.md @@ -0,0 +1,84 @@ +# Send + +`yapi send` makes quick one-off requests without a config file. +Think of it as curl with better defaults. + +## Basic Usage + +```bash +yapi send https://httpbin.org/get +yapi send https://httpbin.org/post '{"hello":"world"}' +``` + +## Method Detection + +- **No body**: defaults to GET +- **Body provided**: defaults to POST +- **Override with -X**: `yapi send -X PUT https://api.example.com/users/1 '{"name":"Bob"}'` + +## Headers + +```bash +yapi send -H "Authorization: Bearer token123" https://api.example.com/me +yapi send -H "Content-Type: text/plain" -H "X-Custom: value" https://example.com/data +``` + +## JQ Filtering + +Filter the response with `--jq`: + +```bash +yapi send https://api.example.com/users --jq '.[0].name' +yapi send https://api.example.com/users --jq '[.[] | {name, email}]' +``` + +## JSON Output + +Get structured JSON output with metadata: + +```bash +yapi send https://httpbin.org/get --json +``` + +## Protocol Auto-Detection + +The URL scheme determines the protocol: + +```bash +yapi send https://api.example.com/users # HTTP +yapi send tcp://localhost:9877 '{"type":"ping"}' # TCP +yapi send grpc://localhost:50051 # gRPC +``` + +## Verbose Mode + +See request and response details: + +```bash +yapi send -v https://httpbin.org/get +``` + +## Examples + +```bash +# GET request +yapi send https://jsonplaceholder.typicode.com/posts/1 + +# POST with JSON body +yapi send https://httpbin.org/post '{"key":"value"}' + +# PUT with headers +yapi send -X PUT https://api.example.com/items/1 '{"name":"updated"}' \ + -H "Authorization: Bearer ${TOKEN}" + +# Filter response +yapi send https://jsonplaceholder.typicode.com/users --jq '.[].name' + +# TCP raw message +yapi send tcp://localhost:9877 '{"type":"health","params":{}}' +``` + +## See Also + +- `yapi docs protocols` — Protocol-specific details +- `yapi docs jq` — JQ filtering and expressions diff --git a/docs/topics/testing.md b/docs/topics/testing.md new file mode 100644 index 00000000..827a4063 --- /dev/null +++ b/docs/topics/testing.md @@ -0,0 +1,124 @@ +# Testing + +yapi has a built-in test runner for running assertion-based API tests, +with parallel execution and dev server management. + +## Test Files + +By default, `yapi test` runs files matching `*.test.yapi`, `*.test.yapi.yml`, +or `*.test.yapi.yaml`: + +```bash +yapi test # Current directory +yapi test ./tests # Specific directory +yapi test -a # All .yapi files, not just .test ones +``` + +## Writing Tests + +A test file is a normal yapi request file with `expect` assertions: + +```yaml +# users.test.yapi.yml +yapi: v1 +url: https://api.example.com/users +method: GET +expect: + status: 200 + assert: + - . | type == "array" + - . | length > 0 +``` + +Chain files work as tests too — each step's assertions are checked: + +```yaml +# auth-flow.test.yapi.yml +yapi: v1 +chain: + - name: login + url: /auth/login + method: POST + body: + email: ${TEST_EMAIL} + password: ${TEST_PASSWORD} + expect: + status: 200 + assert: + - .token != null + + - name: me + url: /auth/me + headers: + Authorization: Bearer ${login.token} + expect: + status: 200 +``` + +## Parallel Execution + +Run tests concurrently: + +```bash +yapi test -p 4 # 4 parallel threads +``` + +## Dev Server Management + +yapi can start your dev server and wait for it before running tests. + +### Via yapi.config.yml + +```yaml +# yapi.config.yml +yapi: v1 +default_environment: local + +test: + start: npm run dev + wait_on: + - http://localhost:3000/health + wait_timeout: 30s +``` + +### Via CLI Flags + +```bash +yapi test --start "npm run dev" --wait-on http://localhost:3000/health +yapi test --no-start # Skip server startup +``` + +The server is automatically stopped when tests finish or on Ctrl+C. + +## Verbose Output + +```bash +yapi test -v # Show detailed pass/fail per test +``` + +## Environment Selection + +```bash +yapi test -e staging # Run tests against staging environment +``` + +## GitHub Actions + +```yaml +- uses: jamierpond/yapi/action@0.X.X + with: + start: npm run dev + wait-on: http://localhost:3000/health + command: yapi test ./tests -a +``` + +## Exit Codes + +- `0`: All tests passed +- `1`: One or more tests failed + +## See Also + +- `yapi docs assert` — Assertions on status, body, and headers +- `yapi docs chain` — Multi-step request chaining +- `yapi docs environments` — Running tests across environments diff --git a/docs/topics/variables.md b/docs/topics/variables.md new file mode 100644 index 00000000..311161c1 --- /dev/null +++ b/docs/topics/variables.md @@ -0,0 +1,109 @@ +# Variables + +Variables let you parameterize requests — URLs, headers, bodies, assertions. +Use `${VAR}` syntax anywhere in your YAML files. + +## Syntax + +```yaml +url: ${BASE_URL}/api/users/${USER_ID} +headers: + Authorization: Bearer ${API_KEY} +``` + +## Default Values + +Provide fallbacks with `:-`: + +```yaml +url: ${BASE_URL:-http://localhost:3000}/api/users +headers: + X-Timeout: ${TIMEOUT:-30} +``` + +If `BASE_URL` is not set, `http://localhost:3000` is used. + +## Resolution Order + +Variables resolve in this priority (highest first): + +1. **Chain step references**: `${step_name.field}` — data from previous chain steps +2. **Environment vars from yapi.config.yml** — vars defined in the active environment +3. **Shell environment variables** — from your OS/shell +4. **Default values** — specified with `:-` + +## Type Preservation + +When `${VAR}` is the entire value, the original type is preserved: + +```yaml +body: + count: ${step.count} # Stays an integer if count is int + label: "Count: ${step.count}" # String interpolation +``` + +## Environment Variable References in Assertions + +In assertions, use `env.VAR_NAME` to compare against environment variables: + +```yaml +expect: + assert: + - .owner == env.GITHUB_USER + - .region == env.AWS_REGION +``` + +## Variables from Config + +Define variables in `yapi.config.yml`: + +```yaml +yapi: v1 +default_environment: local + +defaults: + vars: + API_VERSION: v1 + +environments: + local: + url: http://localhost:3000 + vars: + API_KEY: dev_key +``` + +Then reference them in request files: + +```yaml +yapi: v1 +url: ${url}/api/${API_VERSION}/users +headers: + X-Api-Key: ${API_KEY} +``` + +## Env Files + +Load variables from `.env` files: + +```yaml +# yapi.config.yml +environments: + prod: + url: https://api.example.com + env_file: .env.prod +``` + +Or per-request: + +```yaml +yapi: v1 +env_files: + - .env.local +url: ${BASE_URL}/api/users +``` + +## See Also + +- `yapi docs environments` — Multi-environment configuration +- `yapi docs chain` — Chain step references +- `yapi docs assert` — Using env vars in assertions From b99289f870476abbf82e78f50c391faf30c48588 Mon Sep 17 00:00:00 2001 From: Jamie Pond Date: Tue, 17 Feb 2026 20:19:16 -0800 Subject: [PATCH 2/4] rm generated --- .gitignore | 1 + cli/internal/docs/topics/assert.md | 130 --------------------- cli/internal/docs/topics/chain.md | 112 ------------------ cli/internal/docs/topics/config.md | 140 ----------------------- cli/internal/docs/topics/environments.md | 101 ---------------- cli/internal/docs/topics/jq.md | 86 -------------- cli/internal/docs/topics/polling.md | 110 ------------------ cli/internal/docs/topics/protocols.md | 119 ------------------- cli/internal/docs/topics/send.md | 84 -------------- cli/internal/docs/topics/testing.md | 124 -------------------- cli/internal/docs/topics/variables.md | 109 ------------------ docs/commands/yapi.md | 42 ------- docs/commands/yapi_about.md | 32 ------ docs/commands/yapi_docs.md | 33 ------ docs/commands/yapi_history.md | 29 ----- docs/commands/yapi_import.md | 34 ------ docs/commands/yapi_list.md | 29 ----- docs/commands/yapi_lsp.md | 28 ----- docs/commands/yapi_run.md | 38 ------ docs/commands/yapi_send.md | 45 -------- docs/commands/yapi_share.md | 28 ----- docs/commands/yapi_stress.md | 33 ------ docs/commands/yapi_test.md | 42 ------- docs/commands/yapi_validate.md | 34 ------ docs/commands/yapi_version.md | 29 ----- docs/commands/yapi_watch.md | 31 ----- 26 files changed, 1 insertion(+), 1622 deletions(-) delete mode 100644 cli/internal/docs/topics/assert.md delete mode 100644 cli/internal/docs/topics/chain.md delete mode 100644 cli/internal/docs/topics/config.md delete mode 100644 cli/internal/docs/topics/environments.md delete mode 100644 cli/internal/docs/topics/jq.md delete mode 100644 cli/internal/docs/topics/polling.md delete mode 100644 cli/internal/docs/topics/protocols.md delete mode 100644 cli/internal/docs/topics/send.md delete mode 100644 cli/internal/docs/topics/testing.md delete mode 100644 cli/internal/docs/topics/variables.md delete mode 100644 docs/commands/yapi.md delete mode 100644 docs/commands/yapi_about.md delete mode 100644 docs/commands/yapi_docs.md delete mode 100644 docs/commands/yapi_history.md delete mode 100644 docs/commands/yapi_import.md delete mode 100644 docs/commands/yapi_list.md delete mode 100644 docs/commands/yapi_lsp.md delete mode 100644 docs/commands/yapi_run.md delete mode 100644 docs/commands/yapi_send.md delete mode 100644 docs/commands/yapi_share.md delete mode 100644 docs/commands/yapi_stress.md delete mode 100644 docs/commands/yapi_test.md delete mode 100644 docs/commands/yapi_validate.md delete mode 100644 docs/commands/yapi_version.md delete mode 100644 docs/commands/yapi_watch.md diff --git a/.gitignore b/.gitignore index 45b757a3..0ce1b837 100644 --- a/.gitignore +++ b/.gitignore @@ -55,6 +55,7 @@ apps/web/icons coverage.out cli/bin/yapi cli/internal/docs/topics +docs/commands specs .specify .claude/commands/specify.* diff --git a/cli/internal/docs/topics/assert.md b/cli/internal/docs/topics/assert.md deleted file mode 100644 index 98ee788f..00000000 --- a/cli/internal/docs/topics/assert.md +++ /dev/null @@ -1,130 +0,0 @@ -# Assertions - -Assertions let you validate HTTP responses — status codes, body content, and headers. -They're the core of yapi's testing capability. - -## Status Expectations - -```yaml -expect: - status: 200 # Exact match - status: [200, 201, 204] # Any of these -``` - -## Body Assertions - -Body assertions are JQ expressions that must evaluate to `true`: - -```yaml -expect: - status: 200 - assert: - - .id != null - - .email != null - - .active == true -``` - -### Operators - -All JQ comparison operators work: `==`, `!=`, `>`, `>=`, `<`, `<=` - -```yaml -assert: - - . | length > 0 # Array has items - - .count >= 10 # Numeric comparison - - .name != "" # Not empty string -``` - -### Array Operations - -```yaml -assert: - - . | type == "array" - - . | length > 0 - - .[0].name != null # First element - - .[] | .status == "active" # All items match -``` - -### Type Checks - -```yaml -assert: - - . | type == "array" - - .data | type == "object" - - .count | type == "number" -``` - -## Environment Variable References - -Compare response values against environment variables using `env.VAR_NAME`: - -```yaml -assert: - - .owner.login == env.GITHUB_USER - - .email == env.EXPECTED_EMAIL -``` - -## Header Assertions - -Use the grouped syntax to assert on response headers: - -```yaml -expect: - status: 200 - assert: - headers: - - .["content-type"] | startswith("application/json") - - .["x-request-id"] != null - body: - - .id != null -``` - -When using the grouped syntax, body assertions go under `body:`. - -## Flat vs Grouped Syntax - -**Flat** (all assertions are body assertions): -```yaml -assert: - - .id != null -``` - -**Grouped** (separate body and header assertions): -```yaml -assert: - headers: - - .["content-type"] | contains("json") - body: - - .id != null -``` - -## Assertions in Chains - -Each chain step can have its own `expect` block: - -```yaml -chain: - - name: create - url: /api/items - method: POST - body: { title: "test" } - expect: - status: 201 - assert: - - .id != null - - - name: verify - url: /api/items/${create.id} - method: GET - expect: - status: 200 - assert: - - .title == "test" -``` - -## See Also - -- `yapi docs chain` — Multi-step request chaining -- `yapi docs jq` — JQ filtering and expressions -- `yapi docs variables` — Variable interpolation -- `yapi docs testing` — Test runner and CI/CD diff --git a/cli/internal/docs/topics/chain.md b/cli/internal/docs/topics/chain.md deleted file mode 100644 index 0ba67324..00000000 --- a/cli/internal/docs/topics/chain.md +++ /dev/null @@ -1,112 +0,0 @@ -# Request Chaining - -Chains let you execute multiple requests sequentially, passing data between steps. -Login, use the token, verify the result — all in one file. - -## Basic Chain - -```yaml -yapi: v1 -chain: - - name: login - url: https://api.example.com/auth/login - method: POST - body: - username: ${USERNAME} - password: ${PASSWORD} - expect: - status: 200 - assert: - - .token != null - - - name: get_profile - url: https://api.example.com/me - method: GET - headers: - Authorization: Bearer ${login.token} - expect: - status: 200 -``` - -## Step References - -Reference data from previous steps with `${step_name.field}`: - -```yaml -- name: create_user - url: /api/users - method: POST - body: { name: "Alice" } - expect: - assert: - - .id != null - -- name: get_user - url: /api/users/${create_user.id} - method: GET -``` - -### Nested Paths - -Access nested JSON fields with dot notation: - -```yaml -${step_name.data.user.email} # Nested object -${step_name.items[0].id} # Array indexing -``` - -### Where References Work - -Step references work in any string field: URLs, headers, body values, assertions. - -```yaml -- name: verify - url: /api/users/${create.id} - headers: - Authorization: Bearer ${login.token} - expect: - assert: - - .email == env.EXPECTED_EMAIL -``` - -## Type Preservation - -When a `${ref}` is the entire value (not part of a larger string), its type is preserved: - -```yaml -body: - user_id: ${get_user.id} # Stays an integer - name: "User ${get_user.id}" # String interpolation -``` - -## Fail-Fast Behavior - -Chains stop on the first failure: -- If a request fails (network error, timeout), the chain stops -- If an assertion fails, the chain stops -- Subsequent steps are skipped - -## Step Config Inheritance - -Each step can override any base-level config field. Steps inherit from the -top-level config (URL, headers, timeout, etc.): - -```yaml -yapi: v1 -timeout: 10s # Default for all steps - -chain: - - name: fast_check - url: /health - timeout: 2s # Override for this step - - - name: slow_op - url: /process - timeout: 30s # Override for this step -``` - -## See Also - -- `yapi docs assert` — Assertions on status, body, and headers -- `yapi docs variables` — Variable interpolation and resolution -- `yapi docs polling` — Polling with wait_for diff --git a/cli/internal/docs/topics/config.md b/cli/internal/docs/topics/config.md deleted file mode 100644 index 1b769786..00000000 --- a/cli/internal/docs/topics/config.md +++ /dev/null @@ -1,140 +0,0 @@ -# Config Reference - -Every yapi request file starts with `yapi: v1`. This page lists all available fields. - -## Project Layout - -Place a `yapi.config.yml` at your project root to define environments and base URLs. Request files (`.yapi.yml`) can live anywhere beneath it — yapi walks up the directory tree to find the nearest config. - -``` -my-project/ -├── yapi.config.yml # project config (environments, base URLs) -└── yapi/ - ├── homepage.yapi.yml # GET / - ├── sitemap.yapi.yml # GET /sitemap.xml - └── health.yapi.yml # GET /healthz -``` - -### Example: `yapi.config.yml` - -```yaml -yapi: v1 - -default_environment: local - -environments: - local: - url: http://localhost:3000 - prod: - url: https://api.example.com -``` - -### Example: `yapi/homepage.yapi.yml` - -```yaml -yapi: v1 -path: / -method: GET - -headers: - User-Agent: yapi-cli - -expect: - status: 200 -``` - -Because the request file uses `path: /` instead of a full `url`, yapi resolves it against the active environment's base URL. Running `yapi run yapi/homepage.yapi.yml` hits `http://localhost:3000/` by default, or `https://api.example.com/` with `-e prod`. - -## Request Fields - -| Field | Type | Description | -|---|---|---| -| `yapi` | string | **Required.** Version tag. Always `v1`. | -| `url` | string | Full request URL | -| `path` | string | Path appended to environment base URL | -| `method` | string | HTTP method: GET, POST, PUT, PATCH, DELETE | -| `headers` | map | Request headers | -| `query` | map | Query parameters | -| `timeout` | string | Request timeout (e.g., `"4s"`, `"100ms"`) | -| `delay` | string | Wait before executing (e.g., `"5s"`) | -| `insecure` | bool | Skip TLS verification | - -`url` and `path` are mutually exclusive. Use `path` when `yapi.config.yml` provides a base URL. - -## Body Fields - -These are mutually exclusive — use only one: - -| Field | Type | Description | -|---|---|---| -| `body` | map | JSON object body | -| `json` | string | Raw JSON string body | -| `form` | map | Form-encoded body | - -## Response Processing - -| Field | Type | Description | -|---|---|---| -| `jq_filter` | string | JQ expression to transform response | -| `output_file` | string | Save response body to file | -| `content_type` | string | Override content type | - -## GraphQL Fields - -| Field | Type | Description | -|---|---|---| -| `graphql` | string | GraphQL query or mutation | -| `variables` | map | GraphQL variables | - -## gRPC Fields - -| Field | Type | Description | -|---|---|---| -| `service` | string | gRPC service name | -| `rpc` | string | RPC method name | -| `proto` | string | Path to .proto file | -| `proto_path` | string | Proto import path | -| `plaintext` | bool | No TLS for gRPC | - -## TCP Fields - -| Field | Type | Description | -|---|---|---| -| `data` | string | Raw data to send | -| `encoding` | string | `text` (default), `hex`, `base64` | -| `read_timeout` | int | Seconds to wait for response | -| `idle_timeout` | int | Milliseconds before response is considered complete | -| `close_after_send` | bool | Close connection after sending | - -## Testing Fields - -| Field | Type | Description | -|---|---|---| -| `expect` | object | Status and assertion expectations | -| `expect.status` | int/[]int | Expected status code(s) | -| `expect.assert` | list/map | Body and header assertions | -| `wait_for` | object | Polling configuration | -| `chain` | list | Multi-step request chain | - -## Environment Fields - -| Field | Type | Description | -|---|---|---| -| `env_files` | []string | Paths to .env files to load | - -## Project Config (`yapi.config.yml`) - -| Field | Type | Description | -|---|---|---| -| `default_environment` | string | Environment used without `-e` | -| `defaults.vars` | map | Variables for all environments | -| `environments` | map | Environment definitions | -| `environments.{name}.url` | string | Base URL | -| `environments.{name}.vars` | map | Environment-specific variables | -| `environments.{name}.env_file` | string | .env file path | - -## See Also - -- `yapi docs protocols` — Protocol-specific details and examples -- `yapi docs variables` — Variable interpolation -- `yapi docs assert` — Assertion syntax diff --git a/cli/internal/docs/topics/environments.md b/cli/internal/docs/topics/environments.md deleted file mode 100644 index 162aa5db..00000000 --- a/cli/internal/docs/topics/environments.md +++ /dev/null @@ -1,101 +0,0 @@ -# Environments - -Environments let you switch between local, staging, and production configs -without changing your request files. - -## Project Config File - -Create `yapi.config.yml` in your project root: - -```yaml -yapi: v1 - -default_environment: local - -defaults: - vars: - API_VERSION: v1 - SHARED_VAR: shared_value - -environments: - local: - url: http://localhost:3000 - vars: - API_KEY: dev_key - DEBUG: "true" - - staging: - url: https://staging.api.example.com - vars: - API_KEY: ${STAGING_API_KEY} - - prod: - url: https://api.example.com - vars: - API_KEY: ${PROD_API_KEY} - env_file: .env.prod -``` - -## Key Fields - -- **`default_environment`**: Used when `-e` flag is not specified -- **`defaults`**: Variables available in ALL environments -- **`environments`**: Environment-specific settings - - **`url`**: Base URL for requests using `path:` instead of `url:` - - **`vars`**: Environment-specific variables - - **`env_file`**: Path to a `.env` file to load - -## Selecting an Environment - -```bash -yapi run request.yapi.yml -e staging -yapi test ./tests -e prod -``` - -Without `-e`, the `default_environment` is used. - -## How URL Resolution Works - -Request files can use `path:` instead of `url:`: - -```yaml -# request.yapi.yml -yapi: v1 -path: /api/users -method: GET -``` - -The `path` is appended to the environment's `url`. So with `-e local`, -the full URL becomes `http://localhost:3000/api/users`. - -## Variable Precedence - -When the same variable is defined in multiple places: - -1. Chain step references (highest priority) -2. Environment-specific `vars` -3. `defaults.vars` -4. Shell environment variables -5. Default values (`${VAR:-default}`) - -## Env Files - -Load secrets from `.env` files per environment: - -```yaml -environments: - prod: - env_file: .env.prod -``` - -``` -# .env.prod -API_KEY=sk-prod-abc123 -DB_URL=postgres://prod-host/db -``` - -## See Also - -- `yapi docs variables` — Variable interpolation and resolution -- `yapi docs config` — Full YAML config field reference -- `yapi docs testing` — Running tests across environments diff --git a/cli/internal/docs/topics/jq.md b/cli/internal/docs/topics/jq.md deleted file mode 100644 index 7abee7b7..00000000 --- a/cli/internal/docs/topics/jq.md +++ /dev/null @@ -1,86 +0,0 @@ -# JQ Filtering - -JQ lets you filter and transform JSON responses inline — -both for display (`jq_filter`) and for validation (`assert`). - -## Response Filtering - -Use `jq_filter` to transform what gets displayed: - -```yaml -yapi: v1 -url: https://api.example.com/users -method: GET -jq_filter: '[.[] | {name, email}] | sort_by(.name)' -``` - -This filters the response before printing, so you only see what matters. - -## JQ in Assertions - -Assertions are JQ expressions that must evaluate to `true`: - -```yaml -expect: - assert: - - .id != null - - . | length > 0 - - .data | type == "object" - - .[0].name | startswith("A") -``` - -## Common Patterns - -### Check array length -```yaml -assert: - - . | length > 0 - - .items | length == 10 -``` - -### Check type -```yaml -assert: - - . | type == "array" - - .data | type == "object" - - .count | type == "number" -``` - -### String operations -```yaml -assert: - - .name | startswith("test_") - - .email | endswith("@example.com") - - .url | contains("api") -``` - -### Check all items in array -```yaml -assert: - - .[] | .status == "active" # Every item matches - - [.[] | .score > 0] | all # All scores positive -``` - -### Select specific fields -```yaml -jq_filter: '{id, name, email}' # Single object -jq_filter: '[.[] | {id, name}]' # Array of objects -``` - -### Sort and limit -```yaml -jq_filter: 'sort_by(.created_at) | reverse | .[:5]' -``` - -## JQ with yapi send - -Apply JQ filters on the command line: - -```bash -yapi send https://api.example.com/users --jq '.[0].name' -``` - -## See Also - -- `yapi docs assert` — Assertions on status, body, and headers -- `yapi docs send` — Quick one-off requests with --jq flag diff --git a/cli/internal/docs/topics/polling.md b/cli/internal/docs/topics/polling.md deleted file mode 100644 index 6e770862..00000000 --- a/cli/internal/docs/topics/polling.md +++ /dev/null @@ -1,110 +0,0 @@ -# Polling - -The `wait_for` block lets you poll an endpoint until conditions are met. -Useful for async operations, health checks, and eventual consistency. - -## Basic Polling - -```yaml -yapi: v1 -url: https://api.example.com/jobs/123 -method: GET - -wait_for: - until: - - .status == "completed" - period: 2s - timeout: 30s -``` - -This sends GET requests every 2 seconds until `.status == "completed"` or 30 seconds elapse. - -## Fields - -- **`until`**: Array of JQ assertions. ALL must pass to stop polling. -- **`period`**: Fixed delay between attempts (e.g., `"1s"`, `"500ms"`). -- **`backoff`**: Exponential backoff (mutually exclusive with `period`). -- **`timeout`**: Maximum wait time. Default: `30s`. - -## Fixed Period - -Retry at a constant interval: - -```yaml -wait_for: - until: - - .ready == true - period: 1s - timeout: 60s -``` - -## Exponential Backoff - -Start with a short delay, grow exponentially: - -```yaml -wait_for: - until: - - .status == "done" - backoff: - seed: 1s # First wait: 1s - multiplier: 2 # Then 2s, 4s, 8s, 16s... - timeout: 60s -``` - -The delay doubles each attempt: seed, seed*multiplier, seed*multiplier^2, etc. -`multiplier` must be greater than 1. - -## Multiple Conditions - -All `until` conditions must pass simultaneously: - -```yaml -wait_for: - until: - - .status == "completed" - - .result != null - - .errors | length == 0 - period: 2s - timeout: 30s -``` - -## Polling in Chains - -Each chain step can have its own `wait_for`: - -```yaml -chain: - - name: start_job - url: /api/jobs - method: POST - body: { task: "process" } - expect: - status: 202 - assert: - - .job_id != null - - - name: wait_done - url: /api/jobs/${start_job.job_id} - method: GET - wait_for: - until: - - .status == "completed" - period: 2s - timeout: 60s - expect: - assert: - - .result != null -``` - -## Behavior - -- If the request itself fails (network error), polling continues until timeout -- If assertions don't pass, polling retries -- On timeout, the test fails with an error -- On success, execution continues normally (chain proceeds to next step) - -## See Also - -- `yapi docs assert` — Assertions used in until conditions -- `yapi docs chain` — Multi-step request chaining diff --git a/cli/internal/docs/topics/protocols.md b/cli/internal/docs/topics/protocols.md deleted file mode 100644 index 5f28c22c..00000000 --- a/cli/internal/docs/topics/protocols.md +++ /dev/null @@ -1,119 +0,0 @@ -# Protocols - -yapi supports HTTP, gRPC, GraphQL, and TCP as first-class protocols. -Transport is detected from the URL scheme and config fields. - -## HTTP / REST - -The default protocol. Standard request/response: - -```yaml -yapi: v1 -url: https://api.example.com/users -method: POST -content_type: application/json -headers: - Authorization: Bearer ${TOKEN} -body: - name: "Alice" - email: "alice@example.com" -expect: - status: 201 -``` - -### Form Data - -```yaml -yapi: v1 -url: https://example.com/login -method: POST -form: - username: admin - password: ${PASSWORD} -``` - -## GraphQL - -Detected by the `graphql:` field: - -```yaml -yapi: v1 -url: https://countries.trevorblades.com/graphql - -graphql: | - query getCountry($code: ID!) { - country(code: $code) { - name - capital - } - } - -variables: - code: "US" -``` - -GraphQL requests are always POST. The `graphql` field contains your query or mutation, -and `variables` holds the GraphQL variables. - -## gRPC - -Detected by `grpc://` URL scheme. Requires server reflection or proto files: - -```yaml -yapi: v1 -url: grpc://localhost:50051 -service: helloworld.Greeter -rpc: SayHello - -body: - name: "World" -``` - -### With Proto Files - -```yaml -yapi: v1 -url: grpc://localhost:50051 -service: helloworld.Greeter -rpc: SayHello -proto: ./proto/helloworld.proto -proto_path: ./proto - -body: - name: "World" -``` - -### Insecure / Plaintext - -```yaml -plaintext: true # No TLS -insecure: true # Skip TLS verification -``` - -## TCP - -Detected by `tcp://` URL scheme. Raw socket communication: - -```yaml -yapi: v1 -url: tcp://localhost:9877 -data: '{"type":"health","params":{}}' -encoding: text # text (default), hex, base64 -read_timeout: 5 # Seconds to wait for response -idle_timeout: 500 # Milliseconds before considering response complete -close_after_send: false # Keep connection open to read response -``` - -## Auto-Detection Summary - -| Indicator | Protocol | -|---|---| -| `grpc://` URL | gRPC | -| `tcp://` URL | TCP | -| `graphql:` field present | GraphQL | -| Everything else | HTTP | - -## See Also - -- `yapi docs send` — Quick one-off requests (auto-detects protocol) -- `yapi docs config` — Full field reference for all protocols diff --git a/cli/internal/docs/topics/send.md b/cli/internal/docs/topics/send.md deleted file mode 100644 index cd17af0c..00000000 --- a/cli/internal/docs/topics/send.md +++ /dev/null @@ -1,84 +0,0 @@ -# Send - -`yapi send` makes quick one-off requests without a config file. -Think of it as curl with better defaults. - -## Basic Usage - -```bash -yapi send https://httpbin.org/get -yapi send https://httpbin.org/post '{"hello":"world"}' -``` - -## Method Detection - -- **No body**: defaults to GET -- **Body provided**: defaults to POST -- **Override with -X**: `yapi send -X PUT https://api.example.com/users/1 '{"name":"Bob"}'` - -## Headers - -```bash -yapi send -H "Authorization: Bearer token123" https://api.example.com/me -yapi send -H "Content-Type: text/plain" -H "X-Custom: value" https://example.com/data -``` - -## JQ Filtering - -Filter the response with `--jq`: - -```bash -yapi send https://api.example.com/users --jq '.[0].name' -yapi send https://api.example.com/users --jq '[.[] | {name, email}]' -``` - -## JSON Output - -Get structured JSON output with metadata: - -```bash -yapi send https://httpbin.org/get --json -``` - -## Protocol Auto-Detection - -The URL scheme determines the protocol: - -```bash -yapi send https://api.example.com/users # HTTP -yapi send tcp://localhost:9877 '{"type":"ping"}' # TCP -yapi send grpc://localhost:50051 # gRPC -``` - -## Verbose Mode - -See request and response details: - -```bash -yapi send -v https://httpbin.org/get -``` - -## Examples - -```bash -# GET request -yapi send https://jsonplaceholder.typicode.com/posts/1 - -# POST with JSON body -yapi send https://httpbin.org/post '{"key":"value"}' - -# PUT with headers -yapi send -X PUT https://api.example.com/items/1 '{"name":"updated"}' \ - -H "Authorization: Bearer ${TOKEN}" - -# Filter response -yapi send https://jsonplaceholder.typicode.com/users --jq '.[].name' - -# TCP raw message -yapi send tcp://localhost:9877 '{"type":"health","params":{}}' -``` - -## See Also - -- `yapi docs protocols` — Protocol-specific details -- `yapi docs jq` — JQ filtering and expressions diff --git a/cli/internal/docs/topics/testing.md b/cli/internal/docs/topics/testing.md deleted file mode 100644 index 827a4063..00000000 --- a/cli/internal/docs/topics/testing.md +++ /dev/null @@ -1,124 +0,0 @@ -# Testing - -yapi has a built-in test runner for running assertion-based API tests, -with parallel execution and dev server management. - -## Test Files - -By default, `yapi test` runs files matching `*.test.yapi`, `*.test.yapi.yml`, -or `*.test.yapi.yaml`: - -```bash -yapi test # Current directory -yapi test ./tests # Specific directory -yapi test -a # All .yapi files, not just .test ones -``` - -## Writing Tests - -A test file is a normal yapi request file with `expect` assertions: - -```yaml -# users.test.yapi.yml -yapi: v1 -url: https://api.example.com/users -method: GET -expect: - status: 200 - assert: - - . | type == "array" - - . | length > 0 -``` - -Chain files work as tests too — each step's assertions are checked: - -```yaml -# auth-flow.test.yapi.yml -yapi: v1 -chain: - - name: login - url: /auth/login - method: POST - body: - email: ${TEST_EMAIL} - password: ${TEST_PASSWORD} - expect: - status: 200 - assert: - - .token != null - - - name: me - url: /auth/me - headers: - Authorization: Bearer ${login.token} - expect: - status: 200 -``` - -## Parallel Execution - -Run tests concurrently: - -```bash -yapi test -p 4 # 4 parallel threads -``` - -## Dev Server Management - -yapi can start your dev server and wait for it before running tests. - -### Via yapi.config.yml - -```yaml -# yapi.config.yml -yapi: v1 -default_environment: local - -test: - start: npm run dev - wait_on: - - http://localhost:3000/health - wait_timeout: 30s -``` - -### Via CLI Flags - -```bash -yapi test --start "npm run dev" --wait-on http://localhost:3000/health -yapi test --no-start # Skip server startup -``` - -The server is automatically stopped when tests finish or on Ctrl+C. - -## Verbose Output - -```bash -yapi test -v # Show detailed pass/fail per test -``` - -## Environment Selection - -```bash -yapi test -e staging # Run tests against staging environment -``` - -## GitHub Actions - -```yaml -- uses: jamierpond/yapi/action@0.X.X - with: - start: npm run dev - wait-on: http://localhost:3000/health - command: yapi test ./tests -a -``` - -## Exit Codes - -- `0`: All tests passed -- `1`: One or more tests failed - -## See Also - -- `yapi docs assert` — Assertions on status, body, and headers -- `yapi docs chain` — Multi-step request chaining -- `yapi docs environments` — Running tests across environments diff --git a/cli/internal/docs/topics/variables.md b/cli/internal/docs/topics/variables.md deleted file mode 100644 index 311161c1..00000000 --- a/cli/internal/docs/topics/variables.md +++ /dev/null @@ -1,109 +0,0 @@ -# Variables - -Variables let you parameterize requests — URLs, headers, bodies, assertions. -Use `${VAR}` syntax anywhere in your YAML files. - -## Syntax - -```yaml -url: ${BASE_URL}/api/users/${USER_ID} -headers: - Authorization: Bearer ${API_KEY} -``` - -## Default Values - -Provide fallbacks with `:-`: - -```yaml -url: ${BASE_URL:-http://localhost:3000}/api/users -headers: - X-Timeout: ${TIMEOUT:-30} -``` - -If `BASE_URL` is not set, `http://localhost:3000` is used. - -## Resolution Order - -Variables resolve in this priority (highest first): - -1. **Chain step references**: `${step_name.field}` — data from previous chain steps -2. **Environment vars from yapi.config.yml** — vars defined in the active environment -3. **Shell environment variables** — from your OS/shell -4. **Default values** — specified with `:-` - -## Type Preservation - -When `${VAR}` is the entire value, the original type is preserved: - -```yaml -body: - count: ${step.count} # Stays an integer if count is int - label: "Count: ${step.count}" # String interpolation -``` - -## Environment Variable References in Assertions - -In assertions, use `env.VAR_NAME` to compare against environment variables: - -```yaml -expect: - assert: - - .owner == env.GITHUB_USER - - .region == env.AWS_REGION -``` - -## Variables from Config - -Define variables in `yapi.config.yml`: - -```yaml -yapi: v1 -default_environment: local - -defaults: - vars: - API_VERSION: v1 - -environments: - local: - url: http://localhost:3000 - vars: - API_KEY: dev_key -``` - -Then reference them in request files: - -```yaml -yapi: v1 -url: ${url}/api/${API_VERSION}/users -headers: - X-Api-Key: ${API_KEY} -``` - -## Env Files - -Load variables from `.env` files: - -```yaml -# yapi.config.yml -environments: - prod: - url: https://api.example.com - env_file: .env.prod -``` - -Or per-request: - -```yaml -yapi: v1 -env_files: - - .env.local -url: ${BASE_URL}/api/users -``` - -## See Also - -- `yapi docs environments` — Multi-environment configuration -- `yapi docs chain` — Chain step references -- `yapi docs assert` — Using env vars in assertions diff --git a/docs/commands/yapi.md b/docs/commands/yapi.md deleted file mode 100644 index fd09e073..00000000 --- a/docs/commands/yapi.md +++ /dev/null @@ -1,42 +0,0 @@ -## yapi - -yapi is a unified API client for HTTP, gRPC, and TCP - -### Synopsis - -yapi is a unified API client for HTTP, gRPC, GraphQL, and TCP. - -Run 'yapi docs' to browse topic-based documentation. - -``` -yapi [flags] -``` - -### Options - -``` - --binary-output Display binary content to stdout (by default binary content is hidden) - -h, --help help for yapi - --insecure Skip TLS verification for HTTPS requests; use insecure transport for gRPC - --no-color Disable color output - -u, --url string Override the URL specified in the config file -``` - -### SEE ALSO - -* [yapi about](yapi_about) - Show comprehensive yapi developer guide -* [yapi docs](yapi_docs) - Browse topic-based documentation -* [yapi history](yapi_history) - Show yapi command history (default: last 10) -* [yapi import](yapi_import) - Import an external collection (Postman) to yapi format -* [yapi list](yapi_list) - List all yapi config files in the current directory or project -* [yapi lsp](yapi_lsp) - Run the yapi language server over stdio -* [yapi run](yapi_run) - Run a request defined in a yapi config file (reads from stdin if no file specified) -* [yapi send](yapi_send) - Send a quick request without a config file -* [yapi share](yapi_share) - Generate a shareable yapi.run link for a config file -* [yapi stress](yapi_stress) - Load test a yapi config file with concurrent requests -* [yapi test](yapi_test) - Run all *.test.yapi, *.test.yapi.yml, *.test.yapi.yaml files in the current directory or specified directory -* [yapi validate](yapi_validate) - Validate a yapi config file -* [yapi version](yapi_version) - Print version information -* [yapi watch](yapi_watch) - Watch a yapi config file and re-run on changes - -###### Auto generated by spf13/cobra on 17-Feb-2026 diff --git a/docs/commands/yapi_about.md b/docs/commands/yapi_about.md deleted file mode 100644 index 631a2ad6..00000000 --- a/docs/commands/yapi_about.md +++ /dev/null @@ -1,32 +0,0 @@ -## yapi about - -Show comprehensive yapi developer guide - -### Synopsis - -Display a comprehensive developer guide for working with yapi. Includes syntax, examples, best practices, and project organization patterns. - -``` -yapi about [flags] -``` - -### Options - -``` - -h, --help help for about -``` - -### Options inherited from parent commands - -``` - --binary-output Display binary content to stdout (by default binary content is hidden) - --insecure Skip TLS verification for HTTPS requests; use insecure transport for gRPC - --no-color Disable color output - -u, --url string Override the URL specified in the config file -``` - -### SEE ALSO - -* [yapi](yapi) - yapi is a unified API client for HTTP, gRPC, and TCP - -###### Auto generated by spf13/cobra on 17-Feb-2026 diff --git a/docs/commands/yapi_docs.md b/docs/commands/yapi_docs.md deleted file mode 100644 index 972876a3..00000000 --- a/docs/commands/yapi_docs.md +++ /dev/null @@ -1,33 +0,0 @@ -## yapi docs - -Browse topic-based documentation - -### Synopsis - -Browse topic-based documentation for yapi features. -Run 'yapi docs' to see all topics, or 'yapi docs ' to read one. - -``` -yapi docs [topic] [flags] -``` - -### Options - -``` - -h, --help help for docs -``` - -### Options inherited from parent commands - -``` - --binary-output Display binary content to stdout (by default binary content is hidden) - --insecure Skip TLS verification for HTTPS requests; use insecure transport for gRPC - --no-color Disable color output - -u, --url string Override the URL specified in the config file -``` - -### SEE ALSO - -* [yapi](yapi) - yapi is a unified API client for HTTP, gRPC, and TCP - -###### Auto generated by spf13/cobra on 17-Feb-2026 diff --git a/docs/commands/yapi_history.md b/docs/commands/yapi_history.md deleted file mode 100644 index a2172935..00000000 --- a/docs/commands/yapi_history.md +++ /dev/null @@ -1,29 +0,0 @@ -## yapi history - -Show yapi command history (default: last 10) - -``` -yapi history [count] [flags] -``` - -### Options - -``` - -h, --help help for history - --json Output as JSON -``` - -### Options inherited from parent commands - -``` - --binary-output Display binary content to stdout (by default binary content is hidden) - --insecure Skip TLS verification for HTTPS requests; use insecure transport for gRPC - --no-color Disable color output - -u, --url string Override the URL specified in the config file -``` - -### SEE ALSO - -* [yapi](yapi) - yapi is a unified API client for HTTP, gRPC, and TCP - -###### Auto generated by spf13/cobra on 17-Feb-2026 diff --git a/docs/commands/yapi_import.md b/docs/commands/yapi_import.md deleted file mode 100644 index 038e9c23..00000000 --- a/docs/commands/yapi_import.md +++ /dev/null @@ -1,34 +0,0 @@ -## yapi import - -Import an external collection (Postman) to yapi format - -### Synopsis - -Import a Postman collection JSON file and convert it to yapi YAML files. Creates a directory structure mirroring the collection's folder organization. - -``` -yapi import [file] [flags] -``` - -### Options - -``` - -e, --env string Postman environment file (.json) to import variables from - -h, --help help for import - -o, --output string Directory to save imported yapi files (default "./imported") -``` - -### Options inherited from parent commands - -``` - --binary-output Display binary content to stdout (by default binary content is hidden) - --insecure Skip TLS verification for HTTPS requests; use insecure transport for gRPC - --no-color Disable color output - -u, --url string Override the URL specified in the config file -``` - -### SEE ALSO - -* [yapi](yapi) - yapi is a unified API client for HTTP, gRPC, and TCP - -###### Auto generated by spf13/cobra on 17-Feb-2026 diff --git a/docs/commands/yapi_list.md b/docs/commands/yapi_list.md deleted file mode 100644 index af9d237a..00000000 --- a/docs/commands/yapi_list.md +++ /dev/null @@ -1,29 +0,0 @@ -## yapi list - -List all yapi config files in the current directory or project - -``` -yapi list [directory] [flags] -``` - -### Options - -``` - -h, --help help for list - --json Output as JSON -``` - -### Options inherited from parent commands - -``` - --binary-output Display binary content to stdout (by default binary content is hidden) - --insecure Skip TLS verification for HTTPS requests; use insecure transport for gRPC - --no-color Disable color output - -u, --url string Override the URL specified in the config file -``` - -### SEE ALSO - -* [yapi](yapi) - yapi is a unified API client for HTTP, gRPC, and TCP - -###### Auto generated by spf13/cobra on 17-Feb-2026 diff --git a/docs/commands/yapi_lsp.md b/docs/commands/yapi_lsp.md deleted file mode 100644 index 757ddcfb..00000000 --- a/docs/commands/yapi_lsp.md +++ /dev/null @@ -1,28 +0,0 @@ -## yapi lsp - -Run the yapi language server over stdio - -``` -yapi lsp [flags] -``` - -### Options - -``` - -h, --help help for lsp -``` - -### Options inherited from parent commands - -``` - --binary-output Display binary content to stdout (by default binary content is hidden) - --insecure Skip TLS verification for HTTPS requests; use insecure transport for gRPC - --no-color Disable color output - -u, --url string Override the URL specified in the config file -``` - -### SEE ALSO - -* [yapi](yapi) - yapi is a unified API client for HTTP, gRPC, and TCP - -###### Auto generated by spf13/cobra on 17-Feb-2026 diff --git a/docs/commands/yapi_run.md b/docs/commands/yapi_run.md deleted file mode 100644 index cff9a728..00000000 --- a/docs/commands/yapi_run.md +++ /dev/null @@ -1,38 +0,0 @@ -## yapi run - -Run a request defined in a yapi config file (reads from stdin if no file specified) - -### Synopsis - -Run a request defined in a yapi config file (reads from stdin if no file specified). - -Related: yapi docs assert, yapi docs chain, yapi docs variables - -``` -yapi run [file] [flags] -``` - -### Options - -``` - -e, --env string Target environment from yapi.config.yml - -h, --help help for run - --json Output result as JSON with full metadata - --strict-env Strict env mode: error on missing env files, no OS env fallback - -v, --verbose Show verbose output (request details, timing, headers) -``` - -### Options inherited from parent commands - -``` - --binary-output Display binary content to stdout (by default binary content is hidden) - --insecure Skip TLS verification for HTTPS requests; use insecure transport for gRPC - --no-color Disable color output - -u, --url string Override the URL specified in the config file -``` - -### SEE ALSO - -* [yapi](yapi) - yapi is a unified API client for HTTP, gRPC, and TCP - -###### Auto generated by spf13/cobra on 17-Feb-2026 diff --git a/docs/commands/yapi_send.md b/docs/commands/yapi_send.md deleted file mode 100644 index 5b207383..00000000 --- a/docs/commands/yapi_send.md +++ /dev/null @@ -1,45 +0,0 @@ -## yapi send - -Send a quick request without a config file - -### Synopsis - -Send a one-off HTTP or TCP request directly from the command line. -The transport is auto-detected from the URL scheme (tcp://, grpc://, or HTTP by default). - -Examples: - yapi send https://httpbin.org/get - yapi send -X POST https://httpbin.org/post '{"hello":"world"}' - yapi send tcp://localhost:9877 '{"type":"health","params":{}}' - -Related: yapi docs send, yapi docs protocols - -``` -yapi send [body] [flags] -``` - -### Options - -``` - -H, --header strings Custom headers (e.g. -H 'Content-Type: application/json') - -h, --help help for send - --jq string JQ filter to apply to the response - --json Output result as JSON with full metadata - -X, --method string HTTP method (default: GET, or POST if body is provided) - -v, --verbose Show verbose output (request details, timing, headers) -``` - -### Options inherited from parent commands - -``` - --binary-output Display binary content to stdout (by default binary content is hidden) - --insecure Skip TLS verification for HTTPS requests; use insecure transport for gRPC - --no-color Disable color output - -u, --url string Override the URL specified in the config file -``` - -### SEE ALSO - -* [yapi](yapi) - yapi is a unified API client for HTTP, gRPC, and TCP - -###### Auto generated by spf13/cobra on 17-Feb-2026 diff --git a/docs/commands/yapi_share.md b/docs/commands/yapi_share.md deleted file mode 100644 index d57ae19e..00000000 --- a/docs/commands/yapi_share.md +++ /dev/null @@ -1,28 +0,0 @@ -## yapi share - -Generate a shareable yapi.run link for a config file - -``` -yapi share [file] [flags] -``` - -### Options - -``` - -h, --help help for share -``` - -### Options inherited from parent commands - -``` - --binary-output Display binary content to stdout (by default binary content is hidden) - --insecure Skip TLS verification for HTTPS requests; use insecure transport for gRPC - --no-color Disable color output - -u, --url string Override the URL specified in the config file -``` - -### SEE ALSO - -* [yapi](yapi) - yapi is a unified API client for HTTP, gRPC, and TCP - -###### Auto generated by spf13/cobra on 17-Feb-2026 diff --git a/docs/commands/yapi_stress.md b/docs/commands/yapi_stress.md deleted file mode 100644 index 70ccb95e..00000000 --- a/docs/commands/yapi_stress.md +++ /dev/null @@ -1,33 +0,0 @@ -## yapi stress - -Load test a yapi config file with concurrent requests - -``` -yapi stress [file] [flags] -``` - -### Options - -``` - -d, --duration string Duration to run test (e.g., 10s, 1m) - overrides num-requests - -e, --env string Target environment from yapi.config.yml - -h, --help help for stress - -n, --num-requests int Total number of requests to make (default 100) - -p, --parallel int Number of concurrent requests (default 1) - -y, --yes Skip confirmation prompt -``` - -### Options inherited from parent commands - -``` - --binary-output Display binary content to stdout (by default binary content is hidden) - --insecure Skip TLS verification for HTTPS requests; use insecure transport for gRPC - --no-color Disable color output - -u, --url string Override the URL specified in the config file -``` - -### SEE ALSO - -* [yapi](yapi) - yapi is a unified API client for HTTP, gRPC, and TCP - -###### Auto generated by spf13/cobra on 17-Feb-2026 diff --git a/docs/commands/yapi_test.md b/docs/commands/yapi_test.md deleted file mode 100644 index 37656ccf..00000000 --- a/docs/commands/yapi_test.md +++ /dev/null @@ -1,42 +0,0 @@ -## yapi test - -Run all *.test.yapi, *.test.yapi.yml, *.test.yapi.yaml files in the current directory or specified directory - -### Synopsis - -Run all *.test.yapi, *.test.yapi.yml, *.test.yapi.yaml files in the current directory or specified directory. - -Related: yapi docs testing, yapi docs assert - -``` -yapi test [directory] [flags] -``` - -### Options - -``` - -a, --all Run all *.yapi, *.yapi.yml, *.yapi.yaml files (not just test files) - -e, --env string Target environment from yapi.config.yml - -h, --help help for test - --no-start Skip starting the dev server (even if configured in yapi.config.yml) - -p, --parallel int Number of parallel threads to run tests on (default 1) - --start string Command to start the dev server (overrides yapi.config.yml) - -v, --verbose Show verbose output for each test - --wait-on strings URL(s) to wait for before running tests (http://, grpc://, tcp://) - --wait-timeout duration Health check timeout (default 1m0s) -``` - -### Options inherited from parent commands - -``` - --binary-output Display binary content to stdout (by default binary content is hidden) - --insecure Skip TLS verification for HTTPS requests; use insecure transport for gRPC - --no-color Disable color output - -u, --url string Override the URL specified in the config file -``` - -### SEE ALSO - -* [yapi](yapi) - yapi is a unified API client for HTTP, gRPC, and TCP - -###### Auto generated by spf13/cobra on 17-Feb-2026 diff --git a/docs/commands/yapi_validate.md b/docs/commands/yapi_validate.md deleted file mode 100644 index b32c7bd9..00000000 --- a/docs/commands/yapi_validate.md +++ /dev/null @@ -1,34 +0,0 @@ -## yapi validate - -Validate a yapi config file - -### Synopsis - -Validate a yapi config file and report diagnostics. Use - to read from stdin. - -``` -yapi validate [file] [flags] -``` - -### Options - -``` - -a, --all Validate all *.yapi, *.yapi.yml, *.yapi.yaml files in current directory or specified directory - -h, --help help for validate - --json Output diagnostics as JSON -``` - -### Options inherited from parent commands - -``` - --binary-output Display binary content to stdout (by default binary content is hidden) - --insecure Skip TLS verification for HTTPS requests; use insecure transport for gRPC - --no-color Disable color output - -u, --url string Override the URL specified in the config file -``` - -### SEE ALSO - -* [yapi](yapi) - yapi is a unified API client for HTTP, gRPC, and TCP - -###### Auto generated by spf13/cobra on 17-Feb-2026 diff --git a/docs/commands/yapi_version.md b/docs/commands/yapi_version.md deleted file mode 100644 index af563851..00000000 --- a/docs/commands/yapi_version.md +++ /dev/null @@ -1,29 +0,0 @@ -## yapi version - -Print version information - -``` -yapi version [flags] -``` - -### Options - -``` - -h, --help help for version - --json Output version info as JSON -``` - -### Options inherited from parent commands - -``` - --binary-output Display binary content to stdout (by default binary content is hidden) - --insecure Skip TLS verification for HTTPS requests; use insecure transport for gRPC - --no-color Disable color output - -u, --url string Override the URL specified in the config file -``` - -### SEE ALSO - -* [yapi](yapi) - yapi is a unified API client for HTTP, gRPC, and TCP - -###### Auto generated by spf13/cobra on 17-Feb-2026 diff --git a/docs/commands/yapi_watch.md b/docs/commands/yapi_watch.md deleted file mode 100644 index f31f1768..00000000 --- a/docs/commands/yapi_watch.md +++ /dev/null @@ -1,31 +0,0 @@ -## yapi watch - -Watch a yapi config file and re-run on changes - -``` -yapi watch [file] [flags] -``` - -### Options - -``` - -e, --env string Target environment from yapi.config.yml - -h, --help help for watch - --no-pretty Disable pretty TUI mode - -p, --pretty Enable pretty TUI mode -``` - -### Options inherited from parent commands - -``` - --binary-output Display binary content to stdout (by default binary content is hidden) - --insecure Skip TLS verification for HTTPS requests; use insecure transport for gRPC - --no-color Disable color output - -u, --url string Override the URL specified in the config file -``` - -### SEE ALSO - -* [yapi](yapi) - yapi is a unified API client for HTTP, gRPC, and TCP - -###### Auto generated by spf13/cobra on 17-Feb-2026 From 905f404bf8af8f31bb896b1d3528852f75eacc55 Mon Sep 17 00:00:00 2001 From: Jamie Pond Date: Tue, 17 Feb 2026 20:22:30 -0800 Subject: [PATCH 3/4] fix(ci): add sync-docs step before Go build/lint/test The topic docs are now gitignored (copied at build time from docs/topics/ into cli/internal/docs/topics/). CI and Vercel need to run make sync-docs before any Go compilation so go:embed can find the files. Co-Authored-By: Claude Opus 4.6 --- .github/workflows/cli.yml | 8 ++++++++ .github/workflows/codecov.yml | 3 +++ cli/scripts/vercel-build.sh | 3 +++ 3 files changed, 14 insertions(+) diff --git a/.github/workflows/cli.yml b/.github/workflows/cli.yml index 3e54e572..62cff564 100644 --- a/.github/workflows/cli.yml +++ b/.github/workflows/cli.yml @@ -5,12 +5,14 @@ on: branches: [ main, next ] paths: - 'cli/**' + - 'docs/**' - 'examples/**' - '.github/workflows/cli.yml' pull_request: branches: [ main, next ] paths: - 'cli/**' + - 'docs/**' - 'examples/**' - '.github/workflows/cli.yml' workflow_dispatch: @@ -28,6 +30,9 @@ jobs: go-version: '1.25' cache-dependency-path: cli/go.sum + - name: Sync topic docs + run: make sync-docs + - name: Install linters run: make lint-install @@ -50,6 +55,9 @@ jobs: go-version: '1.25' cache-dependency-path: cli/go.sum + - name: Sync topic docs + run: make sync-docs + - name: Download dependencies run: cd cli && go mod download diff --git a/.github/workflows/codecov.yml b/.github/workflows/codecov.yml index b53c45e8..635b6e34 100644 --- a/.github/workflows/codecov.yml +++ b/.github/workflows/codecov.yml @@ -20,6 +20,9 @@ jobs: go-version: '1.24' cache-dependency-path: cli/go.sum + - name: Sync topic docs + run: make sync-docs + - name: Generate coverage working-directory: cli run: go test -coverprofile=coverage.txt -covermode=atomic ./... || true diff --git a/cli/scripts/vercel-build.sh b/cli/scripts/vercel-build.sh index 65ba7b6a..8c7583ba 100755 --- a/cli/scripts/vercel-build.sh +++ b/cli/scripts/vercel-build.sh @@ -38,6 +38,9 @@ DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ") LDFLAGS="-X main.version=${VERSION} -X main.commit=${COMMIT} -X main.date=${DATE}" +echo "Syncing topic docs into CLI embed dir..." +make sync-docs + echo "Building yapi CLI..." cd cli go build -ldflags "${LDFLAGS}" -o ./bin/yapi ./cmd/yapi From f65e620f3fc8b29fa18fe43d4a36a02c5f2eb937 Mon Sep 17 00:00:00 2001 From: Jamie Pond Date: Tue, 17 Feb 2026 20:24:41 -0800 Subject: [PATCH 4/4] fix(ci): use cp instead of rsync for Windows compat, inline sync in vercel rsync isn't available on Windows CI runners. Use rm + cp instead. Inline the sync commands in vercel-build.sh to avoid make dependency. Co-Authored-By: Claude Opus 4.6 --- Makefile | 3 ++- cli/scripts/vercel-build.sh | 4 +++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index 3ce5f7d3..8c60a63f 100644 --- a/Makefile +++ b/Makefile @@ -47,7 +47,8 @@ lint-full: lint sync-docs: @mkdir -p cli/internal/docs/topics - @rsync -a --delete docs/topics/ cli/internal/docs/topics/ + @rm -rf cli/internal/docs/topics/* + @cp docs/topics/*.md cli/internal/docs/topics/ build: sync-docs @echo "Building yapi CLI..." diff --git a/cli/scripts/vercel-build.sh b/cli/scripts/vercel-build.sh index 8c7583ba..bdd00111 100755 --- a/cli/scripts/vercel-build.sh +++ b/cli/scripts/vercel-build.sh @@ -39,7 +39,9 @@ LDFLAGS="-X main.version=${VERSION} -X main.commit=${COMMIT} -X main.date=${DATE echo "Syncing topic docs into CLI embed dir..." -make sync-docs +mkdir -p cli/internal/docs/topics +rm -rf cli/internal/docs/topics/* +cp docs/topics/*.md cli/internal/docs/topics/ echo "Building yapi CLI..." cd cli