API Artifacts¶
What are these files?
Artifacts produced by the API toolchain (see make api, api-install, api-lint, api-test).
- lint/ — OpenAPI schema validation via:
prance,openapi-spec-validator,redocly lint, andopenapi-generator-cli validate - test/ — Schemathesis property tests (optional JUnit)
- node/ — sandboxed Node workspace for CLI tooling (no root pollution)
- server.log — dev server telemetry
Files & what they’re for
-
server.log — API mock/dev server log.
- Good: Starts cleanly; no stack traces or repeated errors.
- How to use: Start with
make api-testormake api-serve[-bg]; check for stack traces/timeouts.
-
test/schemathesis.log — Schemathesis run output (property/fuzz tests).
- Good: Run completes; no falsifying examples.
- How to use: Investigate falsifying examples; tighten schema or handlers; re-run
make api-test.
-
test/schemathesis.xml — Schemathesis JUnit report (if supported).
- Good: 0 failures / 0 errors. — 0 tests; 0 failures; 0 errors; 0 skipped
- How to use: Publish as CI artifact; wire up test summaries from JUnit.
-
node/tool-versions.txt — Pinned CLI versions in the sandbox.
- Good: Exact versions recorded for reproducibility. — openapi-generator-cli=2.22.0, redocly-cli=2.0.6
- How to use: Commit this file to pin CLI versions; regenerate via
make node_deps.
-
node/npm-install.log — Log of sandboxed
npm install.- Good: Install succeeds; no hard errors.
- How to use: If install fails, open this log; re-run
make node_depsafter fixes.
-
node/package.json — Node workspace manifest (API tooling).
- Good: Scripts usable; deps consistent. — deps: 0 • devDeps: 2 • scripts: 1
- How to use: Edit/inspect scripts; run inside sandbox dir (
artifacts/api/node).
-
node/package-lock.json — NPM lockfile for the sandbox.
- Good: Deterministic installs.
- How to use: Commit to keep installs deterministic in CI.
-
lint/schema.yaml.log — OpenAPI schema lint — results for
schema.yaml.- Good: All validators pass (no errors).
- How to use: Run
make api-lint; fix $ref/type/path issues flagged by prance, openapi-spec-validator, redocly, and openapi-generator.
server.log¶
About this artifact
What it is: API mock/dev server log. What good looks like: Starts cleanly; no stack traces or repeated errors. Tip: Search for ERROR, Traceback, or repeated 5xx responses. Logs are from the foreground/background Uvicorn server launched by the make targets.
test/schemathesis.log¶
About this artifact
What it is: Schemathesis run output (property/fuzz tests). What good looks like: Run completes; no falsifying examples. How it’s produced: make api-test starts the server, waits for /health, then runs schemathesis run against each schema (adds --stateful=links and --junit-xml if supported). Hypothesis DB: stored under artifacts/api/test/hypothesis/ for reproducible shrinking.
test/schemathesis.xml¶
About this artifact
What it is: Schemathesis JUnit report (if supported). What good looks like: 0 failures / 0 errors. Summary: total 0, failures 0, errors 0, skipped 0, time ~0.00s
node/tool-versions.txt¶
About this artifact
What it is: Pinned CLI versions in the sandbox. What good looks like: Exact versions recorded for reproducibility. Resolved versions: openapi-generator-cli=2.22.0, redocly-cli=2.0.6
node/npm-install.log¶
About this artifact
What it is: Log of sandboxed npm install. What good looks like: Install succeeds; no hard errors.
node/package.json¶
About this artifact
What it is: Node workspace manifest (API tooling). What good looks like: Scripts usable; deps consistent. Counts: deps=0, devDeps=2, scripts=1 Sandbox dir: artifacts/api/node/ (no repository root pollution).
node/package-lock.json¶
About this artifact
What it is: NPM lockfile for the sandbox. What good looks like: Deterministic installs.
lint/schema.yaml.log¶
About this artifact
What it is: Lint/validate results for schema.yaml. Validators: prance validate, openapi-spec-validator, redocly lint, openapi-generator-cli validate (all run in sequence). What good looks like: No errors; only informational/warn-level notes at most. Re-run: make api-lint.