data

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

Usage

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.

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

[
  {
    "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.
• 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 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:

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

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.

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.