prism
prism copied to clipboard
stoplightio
SPIKE: some per-property x-faker options don't work, FIgure out why and document
Some Faker options don't work at all:
some_text:
type: string
x-faker:
lorem.paragraphs:
paragraphCount: 2
separator: "\n"
yields
"description": "",
Some don't work as expected:
due_date:
type: string
x-faker:
date.past:
yields the following, such that it can't be used with the string format date-time.
"due_date": "Tue Sep 14 2021 05:34:08 GMT-0500 (Central Daylight Time)",
I'd expect that either the the options that do/don't work would be stated in Prism documentation, or that they match Faker JS documentation.
It would also be nice if unsupported options logged something either when Prism starts, or when fakes cannot be successfully generated.
Examples
openapi: 3.1
paths:
/:
get:
description: Faker options that don't work as expected (or at all)
operationId: brokenFakerOptions
responses:
'200':
content:
application/json:
schema:
type: object
properties:
past:
type: string
x-faker:
date.past:
future:
type: string
x-faker:
date.future:
lorem:
type: string
x-faker:
lorem.paragraphs:
paragraphCount: 2
separator: "\n"
This project uses faker v6, no? I couldn't find the exact reference for the faker version in the docs. The one you've linked to is v7 (or at least, it is now). So stuff might not work.
https://github.com/stoplightio/prism/blob/14fb2d20d48d1d47a36aa050d00785737d5742d8/packages/http/package.json#L19
I've tried using values from the "datetype" and "internet" categories, and they all seem to work. Apart from those two, I've been doing some random sampling, and it doesn't look like the values in any of the other categories are working.
This project uses faker v6, no? I couldn't find the exact reference for the faker version in the docs. The one you've linked to is v7 (or at least, it is now). So stuff might not work.
https://github.com/stoplightio/prism/blob/14fb2d20d48d1d47a36aa050d00785737d5742d8/packages/http/package.json#L19
While this project uses v6 of faker, the json-schema-faker package still uses faker v5. Maybe that also causes some issues.
This is the error I get when I use something simple as "address.streetname":
{
"type": "https://stoplight.io/prism/errors#UNKNOWN",
"title": "TypeError: Cannot read properties of undefined (reading 'address')\n at e (/usr/local/lib/node_modules/@stoplight/prism-cli/node_modules/@faker-js/faker/dist/cjs/faker.js:1:2506)\n at t (/usr/local/lib/node_modules/@stoplight/prism-cli/node_modules/@faker-js/faker/dist/cjs/faker.js:1:2715)\n at Object.get (/usr/local/lib/node_modules/@stoplight/prism-cli/node_modules/@faker-js/faker/dist/cjs/faker.js:1:2858)\n at f.streetSuffix (/usr/local/lib/node_modules/@stoplight/prism-cli/node_modules/@faker-js/faker/dist/cjs/address.js:1:2186)\n at f.streetName (/usr/local/lib/node_modules/@stoplight/prism-cli/node_modules/@faker-js/faker/dist/cjs/address.js:1:1819)\n at Object.<anonymous> (/usr/local/lib/node_modules/@stoplight/prism-cli/node_modules/json-schema-faker/dist/main.cjs.js:1273:25)\n at Object.value (/usr/local/lib/node_modules/@stoplight/prism-cli/node_modules/json-schema-faker/dist/main.cjs.js:1327:49)\n at /usr/local/lib/node_modules/@stoplight/prism-cli/node_modules/json-schema-faker/dist/main.cjs.js:2118:66\n at Object.typecast (/usr/local/lib/node_modules/@stoplight/prism-cli/node_modules/json-schema-faker/dist/main.cjs.js:996:19)\n at traverse (/usr/local/lib/node_modules/@stoplight/prism-cli/node_modules/json-schema-faker/dist/main.cjs.js:2118:30) in /items/0",
"status": 500,
"detail": ""
}
Hi, fyi, I've tried to use the following x-faker options without any success: (they are all generated as lipsum)
firstName:
type: string
x-faker:
name.firstName:
lastName:
type: string
x-faker:
name.lastName:
userName:
type: string
x-faker:
internet.userName:
address:
type: string
x-faker:
address.street:
city:
type: string
x-faker:
address.cityName:
productType:
type: string
x-faker:
company.bsNoun:
Using:
"@stoplight/prism-cli": "^4.10.5" and Node v16.18.0
Would really appreciate if this issue got some attention.
Also second this as today it's not very transparent.
It would also be nice if unsupported options logged something either when Prism starts, or when fakes cannot be successfully generated.
Supported Faker JS API Options
If using the latest NPM build of Prism, use the following Faker JS API documentation to find supported options
https://v6.fakerjs.dev/api/address.html
Reason
The version of Faker that is being used is the Prism dependency https://github.com/stoplightio/prism/blob/65445ef9365d7f1214ccb14324db6e629cb817d5/packages/http/package.json#L19
"dependencies": {
"@faker-js/faker": "^6.0.0",
The semver caret specifies a minumum required version, but allows for minor and patch version greater than the minimum version. This is why the NPM build of Prism is using the latest v6.3.1. If you are building prism locally, it is possible you are using the yarn.lock version of @faker-js/faker v6.0.0. We are updating the lock file to match the latest version to reduce version mismatch.
How to check and update your Faker JS version
locally, in the root of Prism, run
yarn list --depth 0
look for @faker-js/faker and identify the version (at this time it will be at least v6.0.0)
then run
cd packages/http
yarn upgrade @faker-js/faker@^6.0.0
This will give you the latest version that meets the dependency version.
Json Schema Faker (JSF)
The version of JSF in Prism is currently https://github.com/stoplightio/prism/blob/65445ef9365d7f1214ccb14324db6e629cb817d5/packages/cli/package.json#L20 This means https://github.com/json-schema-faker/json-schema-faker/tree/v0.5.0-rcv.40/docs#available-options these options should be available to set at the schema level to override the default jsf.options.
Json Schema Faker is currently using Faker JS v5.5.3. If you attempt to use their UI tool to generate a schema to use with Prism, it is possible that errors will arise with the values you've faked due to these version mismatches.
Confirm Version Mismatch
If you are not sure if the issue you are encountering is due to a version difference / an option not being supported, you can check the latest Faker JS API documentation https://fakerjs.dev/api/. For each api operation, they list Available since v<x.x.x> which allows you to confirm if the operation is supported with the version of Faker JS you are using locally or with the official Prism build.
Schema Explained
The following yaml file was taken from this issue and modified using a mixture of API Operations that were available before and after version v6.0.0
openapi: 3.1
paths:
/:
get:
description: Faker options that don't work as expected (or at all)
operationId: brokenFakerOptions
responses:
'200':
content:
application/json:
schema:
type: object
properties:
datePast:
type: string
x-faker: date.past
format: 'date-time'
dateRecent:
type: string
x-faker: date.recent
dateFuture:
type: string
x-faker: date.future
format: 'date'
randNumber:
type: number
faker: random.number
randNumericAsString:
type: string
x-faker: random.numeric
randNumericAsNumber:
type: number
x-faker: random.numeric
dataTypeTen-or-eleven:
type: number
example: 10
x-faker:
datatype.number:
min: 10
max: 11
dataTypeNumber:
type: number
x-faker: datatype.number
dataTypeBigInt:
type: number
x-faker: datatype.bigInt
dataTypeHexadecimal:
type: string
x-faker:
datatype.hexaDecimal:
- 10
firstName:
type: string
x-faker:
name.firstName:
lastName:
type: string
x-faker:
name.lastName:
userName:
type: string
x-faker:
internet.userName:
addressStreetAsString:
type: string
x-faker:
address.street:
addressStreetAsNumber:
type: number
x-faker:
address.street:
addressStreetName:
type: string
faker: address.streetName
addressCity:
type: string
x-faker:
address.cityName:
addressBuildingNumber:
type: string
x-faker:
address.buildingNumber:
companyProductType:
type: string
x-faker:
company.bsNoun:
companyName:
type: string
x-faker: company.name
companyCompanyName:
type: string
x-faker: company.companyName
loremWord:
type: string
x-faker: lorem.word
loremWords:
type: string
x-faker: lorem.words
loremParagraphsNoParams:
type: string
x-faker: lorem.paragraphs
loremParagraphs:
type: string
x-faker:
lorem.paragraphs:
- 2
- '\n'
randomArrayElements:
type: string
x-faker: random.arrayElements
wordNoun:
type: string
x-faker: word.noun
wordAdjective:
type: string
x-faker: word.adjective
color:
type: string
x-faker: color.rgb
phone:
type: string
x-faker: phone.imei
I saved this yaml as test.yml
Output from latest Prism
prism --version
4.10.5
prism mock test.yml -d
NOTE: I added comments
//after a few of results manually to help build a picture of when different options were supported. These will not be present in the output normally.
{
"addressBuildingNumber": "8715", //addded in v6.2.0
"addressCity": "Killeen",
"addressStreetAsNumber": 48582598.10469937, //added in v7.0.0 - so its defaulting to a random number since its type: number and not supported in the Prism Faker JS version
"addressStreetAsString": "Duis ut commodo esse", //added in v7.0.0- so its defaulting to a random string since its type: string and not supported in the Prism Faker JS version
"addressStreetName": "Cormier Plains",
"color": "ex", //added in v7.0.0 - so its defaulting to a random string since its type: string and not supported in the Prism Faker JS version
"companyCompanyName": "Leffler LLC",
"companyName": "aute et fugiat", //added in v7.4.0 - - so its defaulting to a random string since its type: string and not supported in the Prism Faker JS version
"companyProductType": "action-items",
"dataTypeBigInt": 4503409999954966, //added in v6.0.0
"dataTypeHexadecimal": "0xfe298CBCD1", //added in v6.1.2
"dataTypeNumber": 4255,
"dataTypeTen-or-eleven": 11,
"dateFuture": "2022-12-10",
"datePast": "2022-11-09T00:00:00.0Z",
"dateRecent": "Mon Nov 14 2022 23:35:59 GMT-0700 (Mountain Standard Time)",
"firstName": "Pinkie",
"lastName": "Willms",
"loremParagraphs": "Dignissimos eveniet consequuntur laboriosam eveniet. Qui explicabo nobis. Nemo nihil aspernatur plac", //This is limited to 100 characters due to the default Json Schema Options (jsf.options) set in Prism
"loremParagraphsNoParams": "Vel labore blanditiis. Et eius velit et officiis culpa. Tempore ipsa voluptatum sit eum eveniet exer", //This is limited to 100 characters due to the default Json Schema Options (jsf.options) set in Prism
"loremWord": "laboriosam",
"loremWords": "consequuntur velit blanditiis",
"phone": "32-653572-082153-1", //added in v6.2.0
"randNumber": 32374,
"randNumericAsNumber": 7, //added in v6.3.0
"randNumericAsString": "9", //added in v6.3.0
"randomArrayElements": "a,b,c",
"userName": "Misael.Swaniawski",
"wordAdjective": "educated", //added in v6.0.0
"wordNoun": "forehead"
}
Json Schema Faker will return its own faked values when a method is not supported in external Faker JS. This is why some results appear to be working, but not as expected. For example company.name is returning a lorem string and not a faked company name since its not supported in the version of Faker JS used in Prism.
Schema to Faker Quirks
Prism Json Schema Faker (JSF) Default Options
In Prism, some default options have been set for JSF https://github.com/stoplightio/prism/blob/65445ef9365d7f1214ccb14324db6e629cb817d5/packages/http/src/mocker/generator/JSONSchema.ts#L19
This modifies the behavior in a few situations from what you would expect to have returned.
For example, these options are causing lorem.paragraphs, or any long result to be truncated to 100 characters. This makes it appear as though the lorem.paragraphs API Operation is not working, even though it is.
We are opening another issue to take a second look at these defauult options and hopefully close the gap of what is expected to be returned and what is currently getting returned.
If you want to override these at the schema level, you can set the x-json-schema-faker options for the schema.
For example, you could add this at the top of the test.yaml:
openapi: 3.1.0
x-json-schema-faker:
maxLength: 1000
paths:
/:
get:
and see that the lorem.paragraphs are returning properly
"loremParagraphs": "Quod aperiam non reprehenderit aut autem voluptatibus. Consequuntur voluptatem et quia error aperiam. Beatae aliquid quibusdam. A et eos voluptatem adipisci veritatis eaque sed. Omnis velit aliquam....Ex omnis voluptatem natus voluptate atque. Necessitatibus et enim harum quia aperiam voluptates ex animi. Temporibus nihil omnis molestias ut id. Ut expedita laboriosam et non necessitatibus dolores architecto qui soluta.",
"loremParagraphsNoParams": "Saepe rem doloribus quibusdam omnis. Aspernatur atque occaecati neque quia. Nisi omnis neque qui provident laborum laboriosam. Veniam quo libero natus explicabo sed est omnis aut.\nLibero expedita est sit aliquid voluptate corporis sed. Quia voluptatem consequatur dignissimos dolores non rem delectus qui. Laboriosam fugit dolor est at qui quidem aperiam ea. Deleniti dignissimos ea est.\nEaque ex amet voluptatibus. Veritatis distinctio aut id commodi pariatur reiciendis. Voluptatem sequi corrupti iure blanditiis accusantium commodi beatae maxime.",
There are some options that are not working as expected, even though the documentation states it should. minItems is an example of this.
Params vs Option Params
If the Faker JS documentation for a specific operation has “option” in the name column, those params should be named in the schema:
dataTypeTen-or-eleven:
type: number
example: 10
x-faker:
datatype.number:
min: 10
max: 11
precision: 0.01
This is because the options are passed in as an object to Faker JS Example from the Faker JS documentation:
faker.datatype.number({ min: 10, max: 11, precision: 0.01 })
If the Faker JS documentation doesn’t have "option" in the name, the params should be passed in as an array:
financeAmountWithParams:
type: string
faker:
finance.amount:
- 100
- 10000
- 2
- "$"
This is because the params are passed in as separate params to Faker JS Example from the Faker JS documentation:
faker.finance.amount(5, 10, 2, '$')
This might be why you are seeing some things work with parameters and others not.
Check the Faker JS documentation to see if it's expected as separate params or as an object to determine how to represent it in the schema. If you know the operation is supported but are seeing an unexpected result, its possible the params are getting passed in incorrectly.
Date String
Faker JS returns all date operations as type Date. Date is not a supported json schema type, so JSF returns it as a string.
due_date:
type: string
x-faker:
date.past:
"due_date": "Tue Sep 14 2021 05:34:08 GMT-0500 (Central Daylight Time)",
If you want a specific date string format, you must specify a format in the schema.
past:
type: string
x-faker: date.past
format: "date-time"
which will return
"past": "2021-11-18T00:00:00.0Z",
You can also use format: date
