feat: add --seed CLI flag for deterministic generation of dynamic examples

[ilanashapiro]

Summary

Addresses issue #2590

We introduce a new CLI flag --seed that the user sets to a string. This string is feed as a seed into json-schema-faker as described in json-schema-faker/json-schema-faker#111, and allows for reproducible dynamic examples, which is useful in testing. The user can also set the seed in the Prefer header.

NOTE: if you are using --ignoreExamples for Prism to statically generate examples conforming to a schema, you do NOT need to use the --seed flag as this will have no effect. --ignoreExamples uses json-schema-sampler to statically generate examples, not json-schema-faker:

prism/packages/http/src/mocker/generator/JSONSchema.ts

Line 107 in 0d12d25

tryCatch(() => sampler.sample(source, { ticks: 2500 }, operation), toError),

and json-schema-sampler is already deterministic: https://github.com/stoplightio/json-schema-sampler#:~:text=Deterministic%20(given%20a%20particular%20input%2C%20will%20always%20produce%20the%20same%20output).

Checklist

• The basics
  • I tested these changes manually in my local or dev environment
• Tests
  • Added or updated
  • N/A
• Event Tracking
  • I added event tracking and followed the event tracking guidelines
  • N/A
• Error Reporting
  • I reported errors and followed the error reporting guidelines
  • N/A

Screenshots
We mock the following .yaml spec:

openapi: 3.0.2
paths:
  /pets:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                '$ref': '#/schemas/Pet'
              examples:
                cat:
                  summary: An example of a cat
                  value:
                    id: "string_id"
                    name: 123
                    photoUrls: [[]]
                    status: 135

schemas:
  Pet:
      type: object
      required:
      - name
      - photoUrls
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
          example: doggie
        photoUrls:
          type: array
          xml:
            name: photoUrl
            wrapped: true
          items:
            type: string
        status:
          type: string
          description: pet status in the store
          enum:
          - available
          - pending
          - sold

Mocking with --dynamic and --seed gives us reproducible dynamic responses:

Vs mocking with just --dynamic gives us random/variable dynamic responses:

Finally, if you mock in dynamic mode but without a seed specified, you can still add the seed in the Prefer header. Note how in the following example, the first curl request doesn't add a Prefer header, but the second and third do and specify the same seed, and the second and third responses are identical to one another.

[ilanashapiro]

@dgellow

[ilanashapiro]

Hi @brendarearden! Could we request a review on this from someone on your team? Thank you!

[brendarearden]

Hi @ilanashapiro! I am no longer employed here but I think @lukaszzazulak might be able to help you out!

[dgellow]

LGTM, thanks a lot Ilana 👍

[dgellow]

@lukaszzazulak Can we do something to help speed up a review of this PR?

[ilanashapiro]

Following up -- could @lukaszm-sb or @lukaszzazulak please help us get a review on this either by you or someone else on the Prism team? Thanks!

[tesanchez]

@dgellow Thanks for your commitment here. We are looking into some issues we have with the automation process for deployment for some of the dependencies. As soon as we have some free time we will try to get to reviewing this PR.

[jack-bliss]

this is awesome, thanks!

[lukaszzazulak]

@ilanashapiro sorry for the delay, could you resolve conflicts ?

[ilanashapiro]

@lukaszzazulak conflicts are resolved! thank you for approving the changes!