# data

Source: https://apigenie.pl/techdocs/reference/cli-generate_data

Generate example data for a schema of an OpenAPI document. The command is experimental.

## Usage

```sh
apigenie-generator data --pointer POINTER --output OUTPUT [...OPTIONS] INPUT_FILE
```

## Description

The command reads an OpenAPI 3.0, 3.1 or 3.2 document, takes the schema that `--pointer` points
to, and writes a value that conforms to it. With `--number N` greater than 1 it writes a JSON array
of `N` values. The output is JSON or YAML, chosen by the extension of the output file (`.json`,
`.yaml` or `.yml`). Swagger 2.0 documents are not read; convert them first with
[`convert --to openapi32`](/techdocs/reference/cli-convert).

```sh
apigenie-generator data -p /components/schemas/Money -o money.json -n 2 openapi.yaml
```

```json
[
  {
    "amount": "-841701990.0826",
    "currency": "ITG"
  },
  {
    "amount": "-70238.2",
    "currency": "NOO"
  }
]
```

The pointer can name any schema of the document: a component (`/components/schemas/Pet`), a
property (`/components/schemas/Pet/properties/tags`) or the schema of a parameter or a body.
References inside the schema are followed when they are local (`#/...`).

How values are made:

- `enum` and `const` values are taken from the schema. Schema `example`, `examples` and `default`
  values are not used.
- Numbers and integers stay within the schema's `minimum`, `maximum` and exclusive bounds. A bound
  the schema doesn't give comes from the configuration: -10 to 10 by default.
- Strings with a `format` get a value of that format: `uuid`, `date`, `date-time`, `time`,
  `duration`, `email`, `idn-email`, `hostname`, `idn-hostname`, `ipv4`, `ipv6`, `uri`, `url`,
  `iri`, `uri-reference`, `iri-reference`, `uri-template`, `byte` and `password`. Strings with a
  `pattern` match the regular expression. Other strings are words of placeholder text, of a length
  within `minLength` and `maxLength`, or within the configured range (0 to 10) when the schema
  gives neither.
- Arrays have between `minItems` and `maxItems` items, or a number within the configured range (0
  to 10) when the schema gives neither.
- Objects have all their required properties and a random selection of the optional ones, within
  `minProperties` and `maxProperties`.
- `allOf` members are merged; `oneOf` and `anyOf` produce a value of one of the alternatives; a
  schema with several types (`type: [string, "null"]`) produces a value of one of them.
- A schema with an `x-faker` extension gets its value from a faker provider (see "Extensions"), as
  in [`apigenie-server`](/techdocs/reference/cli-server#scenarios-and-extensions).
- Recursive schemas end: below a nesting depth of 16, objects only get their required properties
  and arrays their minimum number of items.

Values are random: each run writes different data.

A schema that can't produce a value (a `false` schema, an unresolved reference, a `minimum` greater
than its `maximum`) stops the command with an error.

## Extensions

| Extension | Effect |
| --------- | ------ |
| `x-faker` | the [faker provider](/techdocs/reference/cli-faker) that makes the value of a schema: a function name, `{name: [arguments]}`, or `{provider, args, options}` |
| `x-apigenie-mock-faker` | the same as `x-faker`, which it takes precedence over |

The extensions can live in an overlay for this target instead of in the document, e.g.
`data.overlay.yaml`:

```yaml
overlay: 1.0.0
info:
  title: Data fakers
  version: 1.0.0
actions:
  - target: $.components.schemas.User.properties.email
    update:
      x-faker: internet.email
```

```sh
apigenie-generator data -p /components/schemas/User openapi.yaml --overlay data.overlay.yaml -o user.json
```

## Options

### -c, --config

Path to the configuration file to use. See the "Configuration" section for more information.

### --overlay OVERLAY

Path to an OpenAPI Overlay (1.0 to 1.2) applied to the input before generating, e.g. one setting the
extensions of the "Extensions" section. Can be repeated: the overlays apply in order, after those
listed under `commands.generate.data.overlay` in the configuration file (with paths relative to it).
Warnings and errors about a value an overlay set point to the overlay.

### --strict

Makes an overlay action whose target selects nothing an error (exit status 2, nothing is generated)
instead of a warning (`OVERLAY:LINE:COL: action #N (TARGET) selects no nodes.`).

### -p, --pointer

Required. JSON pointer to the schema in the input document, e.g. `/components/schemas/User`. A
pointer that doesn't point to a schema is an error (`Schema not found at '...'`).

### -o, --output

Required. Path to the output file. Its extension, `.json`, `.yaml` or `.yml`, sets the format.

### -n, --number

Number of values to generate, a positive integer; 1 by default. With a number greater than 1 the
output is an array.

## Configuration

The `commands.generate.data` section of the configuration file sets the ranges used where a schema
doesn't give its own bounds.

```yaml
version: '1.0'
commands:
  generate:
    data:
      minimum: 0
      maximum: 1000
      minLength: 1
      maxLength: 20
      minItems: 1
      maxItems: 3
```

| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
| `minimum` | number | `0` | Lower bound of numbers and integers whose schema has no lower bound. |
| `maximum` | number | `10` | Upper bound of numbers and integers whose schema has no upper bound. |
| `minLength` | integer | `0` | Minimum length of strings whose schema has neither `minLength` nor `maxLength`. |
| `maxLength` | integer | `10` | Maximum length of strings whose schema has no `maxLength`. |
| `minItems` | integer | `0` | Minimum number of items of arrays whose schema has neither `minItems` nor `maxItems`. |
| `maxItems` | integer | `10` | Maximum number of items of arrays whose schema has no `maxItems`. |
| `minProperties` | integer | `0` | Read and checked, but objects are only limited by their schema. |
| `maxProperties` | integer | `10` | Read and checked, but objects are only limited by their schema. |

Without a configuration file the numeric range is -10 to 10. When the `data` section is present, a
key it leaves out takes the default of the table, so `minimum` becomes 0 unless it is given. A
minimum greater than its maximum, or a negative count, is an error.