# OpenAPI Stub from JSON

Generate an OpenAPI 3.1 operation stub from sample request and response JSON, with inferred schemas, parameters, examples, and YAML or JSON output.

## Run it

- **CLI:** `gizza tool openapi-stub-from-json 'request_json={
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "active": true
}'`
- **Web:** https://gizza.ai/tools/openapi-stub-from-json/
- **Agents:** machine-readable descriptor (parameters JSON Schema) at https://gizza.ai/tools/openapi-stub-from-json/tool.json

## Inputs

- `request_json` — Sample request JSON _(field)_
- `response_json` — Sample response JSON _(field)_
- `method` — HTTP method _(field)_
- `path` — Path _(field)_
- `query` — Sample query string _(field)_
- `status` — Response status _(field)_
- `content_type` — Content type _(field)_
- `operation_id` — Operation ID _(field)_
- `tag` — Tag _(field)_
- `title` — API title _(field)_
- `api_version` — API version _(field)_
- `server_url` — Server URL _(field)_
- `security` — Security _(field)_
- `format` — Output format _(field)_
- `components` — Use component schemas _(field)_
- `extract_nested` — Extract nested components _(field)_
- `required_props` — Mark observed properties required _(field)_
- `detect_formats` — Detect string formats _(field)_
- `include_examples` — Include examples _(field)_
- `include_error_responses` — Add 400/500 error responses _(field)_

## Output

- OpenAPI document (text)

## Query parameters

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

- `request_json` — Sample request JSON
- `response_json` — Sample response JSON
- `method` — HTTP method
- `path` — Path
- `query` — Sample query string
- `status` — Response status
- `content_type` — Content type
- `operation_id` — Operation ID
- `tag` — Tag
- `title` — API title
- `api_version` — API version
- `server_url` — Server URL
- `security` — Security
- `format` — Output format
- `components` — Use component schemas
- `extract_nested` — Extract nested components
- `required_props` — Mark observed properties required
- `detect_formats` — Detect string formats
- `include_examples` — Include examples
- `include_error_responses` — Add 400/500 error responses

Example: `https://gizza.ai/tools/openapi-stub-from-json/?request_json=%7B%0A%20%20%22name%22%3A%20%22Ada%20Lovelace%22%2C%0A%20%20%22email%22%3A%20%22ada%40example.com%22%2C%0A%20%20%22active%22%3A%20true%0A%7D&response_json=%7B%0A%20%20%22id%22%3A%207%2C%0A%20%20%22name%22%3A%20%22Ada%20Lovelace%22%2C%0A%20%20%22email%22%3A%20%22ada%40example.com%22%2C%0A%20%20%22created_at%22%3A%20%222026-08-21T07%3A00%3A00Z%22%0A%7D&method=post&path=%2Fusers%2F%7BuserId%7D&query=include%3Dprofile%26active%3Dtrue%26limit%3D25&status=200&content_type=application%2Fjson&operation_id=createUser&tag=Users&title=Sample%20API&api_version=1.0.0&server_url=https%3A%2F%2Fapi.example.com%2Fv1&security=none&format=yaml&components=true&extract_nested=true&required_props=true&detect_formats=true&include_examples=true&include_error_responses=true`

---

## What this tool does

Paste sample request and response JSON and this tool generates a complete OpenAPI 3.1 path-and-operation stub. It infers JSON Schema from the samples, wires those schemas into `requestBody` and `responses`, adds path and query parameters, and can emit YAML or JSON for pasting into a larger spec.

It is designed for the early documentation step: you have example payloads from a client, a test fixture, a log, or a prototype, and you want a deterministic OpenAPI starting point instead of an empty path block.

It can generate:

- request and response body schemas from JSON objects, arrays, scalars, and nulls;
- `required` lists based on observed object keys;
- string formats such as email, URI, UUID, date, date-time, and IPv4;
- component schemas plus `$ref`, or inline schemas;
- path parameters from `/things/{thingId}` and typed query parameters from a sample query string;
- optional bearer, basic, or `X-API-Key` security boilerplate;
- optional generic 400 and 500 error responses.

## Worked example

Use this request:

```json
{"name":"Ada Lovelace","email":"ada@example.com","active":true}
```

and this response:

```json
{"id":7,"name":"Ada Lovelace","email":"ada@example.com","created_at":"2026-08-21T07:00:00Z"}
```

with **Method: POST**, **Path: `/users`**, and **Operation ID: `createUser`**. The YAML output includes a path operation like:

```yaml
openapi: 3.1.0
paths:
  /users:
    post:
      operationId: createUser
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
```

The generated component schemas infer `email` as a formatted string, `active` as boolean, `id` as integer, and `created_at` as `date-time`. Review the descriptions, validation rules, enum choices, headers, and auth scopes before publishing the spec.

## Limits and edge cases

- This generates **one operation per run**. Use it repeatedly for multiple endpoints, or use a HAR-to-OpenAPI workflow when you have a whole captured session.
- A sample can only show what it contains. It cannot infer enums, minimum/maximum values, regex patterns, length limits, auth scopes, headers, pagination semantics, or business descriptions.
- Empty arrays become arrays with unconstrained item schemas; `null` values become OpenAPI 3.1 JSON Schema null types but do not reveal the intended non-null type.
- Array-of-object samples are merged across every element. Keys present in every object stay required; keys seen only in some elements become optional.
- The output is a stub. Treat it as a structured first draft, then edit names, summaries, descriptions, examples, response coverage, and validation constraints.

## FAQ

<details>
<summary>Is the output OpenAPI 3.0 or 3.1?</summary>

The document uses OpenAPI 3.1.0. That means JSON Schema nulls are represented with the JSON Schema type system instead of the older OpenAPI 3.0 `nullable` keyword.

</details>

<details>
<summary>Does it send my JSON anywhere?</summary>

No. The page runs the Rust WebAssembly generator in your browser, and CLI/chat runs are local to the gizza runtime. There is no network fetch or remote schema service.

</details>

<details>
<summary>How are path parameters generated?</summary>

Any braced path segment, such as `/users/{userId}`, becomes a required `in: path` parameter with a string schema. The sample JSON does not know the path parameter type, so tighten it by hand if the ID is numeric or UUID-shaped.

</details>

<details>
<summary>When should I turn off component schemas?</summary>

Leave components on when you want reusable request/response schemas. Turn them off for tiny examples, documentation snippets, or tests where an inline schema is easier to read.

</details>

## Related tools

- [Absolute value, sign, or negation for a whole column](https://gizza.ai/tools/absolute-value-transformer/): Paste a column of numbers and apply absolute value, sign extraction (-1/0/1), sign flipping, or force-negative to every value at once, with rounding and an audit table.
- [Adjacency Matrix Converter](https://gizza.ai/tools/adjacency-matrix-converter/): Convert a graph between edge list, adjacency matrix, and incidence matrix — directed or undirected, weighted or not. Free, private, runs in your browser.
- [Amazon Order Analyzer](https://gizza.ai/tools/amazon-order-analyzer/): Paste an Amazon order-history CSV export to summarize total spend by month, top items, and category breakdowns. Browser-only, private, with Markdown or JSON output.
- [ARFF Converter](https://gizza.ai/tools/arff-converter/): Convert Weka ARFF datasets to CSV and CSV tables back to ARFF locally — nominal attributes, numeric types, dates, sparse rows, missing values, and type rows.
- [Avro to JSON Converter](https://gizza.ai/tools/avro-to-json/): Decode Apache Avro Object Container Files (.avro / OCF) to JSON, NDJSON, or the embedded schema — no .avsc needed, free and private in your browser.