Redoc: Render JsonSchema constraints

[RomanHotsiy]

• [x] readOnly
• [x] minLength
• [x] maxLength
• [x] pattern
• [ ] minItems
• [ ] maxItems
• [ ] multipleOf
• [x] defaults
• [x] file payload
• [x] readOnly - don't show readOnly fields in request schema
• [x] No need to mark readOnly in response

to be continued...

[RomanHotsiy]

Defaults are supported for primitive types only. Need to add this to the known issues

[MikeRalphson]

@RomanGotsiy Should dividedBy actually be multipleOf? I don't recognise it from the Swagger spec or JSON Schema draft 4.

[RomanHotsiy]

@MikeRalphson yes, you're right. Updated.
Thanks

[nakedible-p]

I know this is marked as post v1.0, but I'd like to mention that we use "pattern" a lot in our API definitions - almost every field is solely determined by pattern - because it is a very simple way to document what kind of values are accepted. Showing that somehow in the rendered documentation would be important for us.

[RomanHotsiy]

@nakedible-p, pattern should be easy to add. I will try to have it done for the next minor release

[RomanHotsiy]

@nakedible-p finally get to this.
What do you think of the following representation?

Maybe you have better idea?

[nakedible-p]

I think it is perfect. Slashes are the universal regexp indicator.

[RomanHotsiy]

Great, hopefully will publish new minor release with this today. Max - tomorrow.

[RomanHotsiy]

@nakedible-p New version is released.

[fgabolde]

Hello, any hope for minItems and maxItems ? There is already support for minLength and maxLength which are basically the same thing for strings.

[RomanHotsiy]

@fgabolde do you have any ideas of how this may look in ReDoc? Similar to minLength and maxLength?

[fgabolde]

Yeah, probably. Right now a size constraint on a string is represented like this:

• [ 2 .. 8 ] characters with both constraints set
• <= 8 characters, max only
• >= 2 characters, min only

Just replacing "characters" with "items" sounds good to me.

[fgabolde]

I don't see the pattern in strings that are used as array items, e.g.:

# definition
HTTPSURL:
  type: string
  format: uri
  pattern: "^https?"

# this one displays "/^https?/" as expected
Thing:
  type: object
  properties:
    single:
      $ref: '#/HTTPSURL'

# this one does not
ManyThings:
  type: object
  properties:
    multiple:
      type: array
      items:
        $ref: '#/HTTPSURL'

I do see the <uri> from the format in both cases, and if I add minLength it works too.

This is Redoc 1.21.2.

[handrews]

@RomanGotsiy Thank you for the fantastic documentation tool!

However, I'm confused about readOnly _(which is more a result of how OpenAPI has specified it than how ReDoc handles is, which I understand flows from that definition- that said, it would be great if there were a bit more flexibility)._

For a POST-to-create I can understand stripping out readOnly fields, although not all POST requests have those semantics so it's a somewhat shaky assumption.

For GET and PUT, the HTTP semantics are that the GET response and PUT request are both representations of the target resource, so you should be able to do a GET, modify some fields, and PUT it right back. As long as you don't change the readOnly fields, it should be fine (yes, I realize that OpenAPI doesn't like this, but it's a SHOULD and not a MUST and it's ridiculously burdensome to make clients strip out fields when doing GET-modify-PUT).

Similarly, if I want to make a copy of a resource, I'll do a GET of it, tweak it, and then POST the tweaked version back to the collection.

In order to make this behavior clear, the readOnly constraint should be rendered on both requests and responses. Would you be open to some sort of option for displaying it as a constraint? I would be happy to write a PR.

[RomanHotsiy]

@handrews yeah, you're right. That's an incorrect assumption 🙈

I think we can add configuration options to disable stripping out and mark fields as readOnly/readWrite instead.

I will try to do in once I find some time. But your PR would be much appreciated!

[handrews]

@RomanGotsiy I'll see if I can put something together in the next week-ish. I took a look and it looks reasonably straightforward- nice job piping the settings through.

Looks like the request body behavior is set in components/Parameters/Parameters.tsx, response body in components/Responses/ResponseDetails.tsx and examples for both requests and responses in services/models/MediaType.ts. And associated tests. Let me know if you can think of any other places offhand.

[calamarico]

@fgabolde I also have the problem that I can't see the pattern in Array of Strings. Did you find the problem with that?