Rich 'schema' support for query params and other fields?

[aliaksei-taliuk]

I'm curious about how to put some important information about param/field constraints/format according to the Open API 3.0 spec: https://swagger.io/specification/#schema-object. Especially, constraints info is quite important.

Could you please point me to something if it is already supported?

Currently, I can only see the next information for the 'schema':

        schema:
          type: string

As far as I understand Spring REST Docs supports flexible 'attributes' approach that can be then integrated with custom templates for snippets while this is not the use case for Open API 3.0 generation. Does it worth some automated integration on your side and somehow automatically transform Bean Validation constraints into Open API Spec?

Thanks in advance.

[ozscheyge]

Hey @aliaksei-taliuk ,

this project supports automatically generating the JSON schema constraints based on Bean Validation constraints, see https://github.com/ePages-de/restdocs-api-spec#documenting-bean-validation-constraints

Are those docs sufficient?

[aliaksei-taliuk]

@ozscheyge Thanks a lot for a quick reply! I will try it. Btw, I would also appreciate code samples because after the first read I didn't understand well this part of the documentation, to be frank.

[ozscheyge]

@ozscheyge Thanks a lot for a quick reply! I will try it. Btw, I would also appreciate code samples because after the first read I didn't understand well this part of the documentation, to be frank.

Hey, no problem!

The tests should serve as an example: https://github.com/ePages-de/restdocs-api-spec/blob/master/restdocs-api-spec-mockmvc/src/test/kotlin/com/epages/restdocs/apispec/ResourceSnippetIntegrationTest.kt#L71-L88

1. Shows a data class annotated with @Length and @NotEmpty validation constraints
2. You can then use ConstrainedFields constructor to extract those constraints. Use the ConstrainedFields' factory methods to create regular Spring Restdocs FieldDescriptors

[aliaksei-taliuk]

@ozscheyge Great! Thanks a lot for the snippet you provided. Now it's clear how it suppose to work)

But seems that it still doesn't solve my problem, because I need to apply it not for 'fields', but for 'parameters'. I've moved them into model class containing all relevant constraints info:

@EitherIdsOrBarcodeId
public class ReadAlbumsRequest {

    @Size(max = 20)
    private List<@Digits(integer = Integer.MAX_VALUE, fraction = 0) @Positive @Max(Integer.MAX_VALUE) String> ids;

    @Barcode
    private String barcodeId;

    @NotBlank
    @ISO2CountryCode
    private String countryCode;

}

This model is treated as a set of request parameters.

And unfortunately, I didn't find any proper way how to add constraints-related info for params (only if into the description section).

I'd appreciate any ideas if any!

Thanks a lot for your help!

[ozscheyge]

@aliaksei-taliuk that's an interesting use-case!

Anyway, we are limited by https://docs.spring.io/spring-restdocs/docs/2.0.x/api/index.html?org/springframework/restdocs/constraints/ValidatorConstraintResolver.html which is used internally in our ConstrainedFields implementation. Further we are limited by our ConstraintResolver which lists all validation constraints this project supports and JsonSchemaFromFieldDescriptorsGenerator which maps the validation constraints to JsonSchema used by both OpenAPI 2, 3 generators.

Without further investigation, I couldn't tell whether it's Spring Restdocs fault of not detecting the constraints annotated on the String type parameter of your ID list (could be detected by setting a breakpoint) or whether it's only this projects fault of not handling your kind of constraints (Digits, Positive, Max are not supported by our ConstraintResolver, #199 tries to address this for Max. Digits could probably be mapped to a special Pattern constraint).