swagger-api / swagger-api/swagger-ui

Swagger fails to generate a valid example for complex regex patterns.

Open
#8,033 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
29k
Forks
9.3k
Avg merge
2d 23h
Merged PRs (30d)
25

Description

Q&A (please complete the following information)
  • OS: Windows 11
  • Browser: Brave, Firefox
  • Version: latest?
  • Method of installation: yarn]
  • Swagger-UI version: 4.6.2
  • Swagger/OpenAPI version: Swagger 2.0
Content & configuration

Example Swagger/OpenAPI definition:

{
    type: 'string',
    pattern: '^[A-Za-z0-9]+\.(png|jpg|jpeg){1}$',
    minLength: 39,
    maxLength: 54,
    description: 'A randomly generated unique id with the file extension',
}
Describe the bug you're encountering

Swagger does not generate a valid example for complex regex patterns. It generates a random string that does not match the provided pattern.

Initially this was my regex ^(?=.{39,54}$)([A-Za-z0-9]+\.(png|jpg|jpeg){1})$, it was completely ignoring the length check (besides not matching the extension) then I read somewhere that the first check it's not supported, so I began to use minLength and maxLength removing the need for the first check. Now they are matching the length specified in the properties, but still not matching the regex pattern ^[A-Za-z0-9]+\.(png|jpg|jpeg){1}$.

Actually not even this website https://onlinestringtools.com/generate-string-from-regex can generate a proper one. My guess is the specification used by Swagger (ECMA-262 or some customized version) might have properties/limitations I'm not aware of. The regex patterns I'm producing work just fine and pass my own tests locally and on websites such as https://regexr.com/ and https://www.regexpal.com/.

I'd like to hear your take on the issue and if there's any workaround for it, besides strictly defining the example.

To reproduce...

Steps to reproduce the behavior:

  1. Create a field for a string that requires a complex regex pattern:
    type: 'string',
    pattern: '^[A-Za-z0-9]+\.(png|jpg|jpeg){1}$',
    minLength: 39,
    maxLength: 54,
    description: 'A randomly generated unique id with the file extension',

  1. Make sure everything else is fine.
  2. Run the server and go see the generated documentation
  3. See the error
Expected behavior

I expected swagger to be able to generate a proper string that matches the given regex.

Screenshots

Sometimes the extension doesn't appear at all, and you can try to test using the generated string, it fails.
img1

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the Swagger 2.0 definition in the issue and tracing how Swagger UI generates examples for string schemas with pattern, minLength, and maxLength. Done means the displayed example matches the supplied regex and length constraints, with regression coverage for the reported pattern.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation, frontend
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.