# Generate curl Commands from OpenAPI

Generate ready-to-run curl commands from an OpenAPI or Swagger spec. Build sample path, query, header and body values locally in your browser.

## Run it

- **CLI:** `gizza tool openapi-to-curl "Paste OpenAPI 3.x or Swagger 2.0 JSON/YAML here"`
- **Web:** https://gizza.ai/tools/openapi-to-curl/
- **Agents:** machine-readable descriptor (parameters JSON Schema) at https://gizza.ai/tools/openapi-to-curl/tool.json

## Inputs

- `spec` — OpenAPI / Swagger spec _(field)_
- `input_format` — Input format _(field)_
- `base_url` — Base URL override _(field)_
- `auth` — Authentication _(field)_
- `auth_value` — Credential value (optional) _(field)_
- `methods` — Method filter _(field)_
- `tags` — Tag filter _(field)_
- `path_filter` — Path contains _(field)_
- `include_optional` — Include optional params and fields _(field)_
- `output_format` — Output format _(field)_
- `multiline` — Multiline commands _(field)_
- `pretty_body` — Pretty-print JSON bodies _(field)_
- `include_comments` — Include endpoint comments _(field)_
- `max_depth` — Schema expansion depth _(field)_

## Output

- curl examples (text)

## Query parameters

Open the tool pre-filled and auto-run via URL:

- `spec` — OpenAPI / Swagger spec
- `input_format` — Input format
- `base_url` — Base URL override
- `auth` — Authentication
- `auth_value` — Credential value (optional)
- `methods` — Method filter
- `tags` — Tag filter
- `path_filter` — Path contains
- `include_optional` — Include optional params and fields
- `output_format` — Output format
- `multiline` — Multiline commands
- `pretty_body` — Pretty-print JSON bodies
- `include_comments` — Include endpoint comments
- `max_depth` — Schema expansion depth

Example: `https://gizza.ai/tools/openapi-to-curl/?spec=Paste%20OpenAPI%203.x%20or%20Swagger%202.0%20JSON%2FYAML%20here&input_format=auto&base_url=https%3A%2F%2Fapi.example.com%2Fv1&auth=auto&auth_value=leave%20blank%20for%20%24TOKEN%20%2F%20%24API_KEY%20placeholders&methods=get%2Cpost&tags=pets%2Cadmin&path_filter=%2Fpets&include_optional=true&output_format=shell&multiline=true&pretty_body=true&include_comments=true&max_depth=4`

---

## About this tool

OpenAPI specs are great for machines, but during debugging you often just need a
pasteable `curl` command for every endpoint. This tool reads an OpenAPI 3.x or
Swagger 2.0 document, walks every path and operation, fills in sample path/query
/header/body values, and emits deterministic curl examples without sending any
network requests.

It prefers examples from the spec, then defaults, enum values and schema formats.
Local `$ref`s are resolved so shared schemas still produce useful bodies; remote
references are not fetched, so the tool stays offline and predictable.

### A worked example

Paste this tiny spec:

```yaml
openapi: 3.0.3
servers:
  - url: https://petstore.example.com/v1
paths:
  /pets/{petId}:
    get:
      summary: Get a pet
      parameters:
        - name: petId
          in: path
          required: true
          schema: { type: integer, example: 42 }
        - name: verbose
          in: query
          schema: { type: boolean, default: true }
      responses:
        '200': { description: OK }
```

With the default shell output, the generated command includes the server URL,
path parameter and query parameter:

```bash
BASE_URL="https://petstore.example.com/v1"

# GET /pets/{petId} — Get a pet
curl -X GET \
  "$BASE_URL/pets/42?verbose=true"
```

### Useful controls

- **Base URL override** swaps the server URL without editing the spec.
- **Authentication** can follow the spec or force bearer/basic/API-key placeholders.
- **Method, tag and path filters** narrow a large spec to the endpoints you care about.
- **Include optional params and fields** turns minimal examples into fuller examples.
- **Output format** switches between a shell script, bare commands, Markdown, and JSON records.
- **Schema expansion depth** prevents recursive or very large schemas from exploding.

### Limits and edge cases

- Remote `$ref` targets are not fetched; unresolved values collapse to `null`.
- The generated samples are examples, not contract tests. They may need real IDs,
  tokens or environment-specific hostnames before you run them.
- JSON and YAML OpenAPI 3.x and Swagger 2.0 documents are supported. A document
  without `paths` is rejected.
- Multipart and form request bodies are represented with curl `-F` / `--data-urlencode`
  style flags when the content type calls for it.

## FAQ

<details>
<summary>Does this make any HTTP requests?</summary>

No. It only parses the spec and writes example commands. The generated `curl`
commands are plain text; nothing is sent until you copy one into a terminal and
run it yourself.

</details>

<details>
<summary>Where do request body values come from?</summary>

The sampler uses the most specific hint available: explicit `example` values,
then `default`, then the first enum value, then a format-aware placeholder such as
an email, UUID or date-time. Object schemas include required fields by default;
turn on optional fields when you want a fuller sample body.

</details>

<details>
<summary>How are auth headers handled?</summary>

`auto` reads the operation or top-level security requirements and the declared
security schemes. If a credential value is blank, the output uses shell
placeholders such as `$TOKEN`, `$API_KEY` or `$API_USER:$API_PASSWORD` so secrets
are not baked into generated docs.

</details>

<details>
<summary>Can I generate examples for only part of a large API?</summary>

Yes. Use a comma-separated method filter (`get,post`), a tag filter (`pets`), or a
path substring (`/admin`). Filters combine, so a command must satisfy every
non-empty filter to be included.

</details>

## Related tools

- [JSON Assertion Runner](https://gizza.ai/tools/json-assertion-runner/): Run JSONPath assertions against a JSON payload and get a pass/fail report for tests, fixtures, and API responses.
- [MongoDB Extended JSON Converter](https://gizza.ai/tools/bson-extended-json-converter/): Convert MongoDB Extended JSON ($oid, $date, $numberLong) to and from plain JSON, with canonical or relaxed output, in your browser.
- [Align Text into Neat Columns](https://gizza.ai/tools/column-aligner/): Paste whitespace-, tab-, comma-, or pipe-delimited text and align it into neat fixed-width plain-text columns with Unicode-aware padding.
- [CSV Cell Diff](https://gizza.ai/tools/csv-cell-diff/): Compare two CSVs column-by-column and highlight every individual cell that changed, plus added and removed rows and columns.
- [Compare Two Code Snippets](https://gizza.ai/tools/diff-code/): Paste two code snippets and compare them side by side, with word- or character-level highlighting, a unified patch view, and change stats.