How can I use the useBeanValidation option when generating code in Swagger?

Question

Swagger's code generation for a Spring server has an option called useBeanValidation, but I can't figure out how to use it. I couldn't find any documentation telling me which validations it supports, so I decided to try it out myself. The OpenAPI spec's description of the properties of a schema object lists these properties:

title
multipleOf
maximum
exclusiveMaximum
minimum
exclusiveMinimum
maxLength
minLength
pattern
maxItems
minItems
uniqueItems
maxProperties
minProperties
required
enum

So I tried adding some of these properties to fields of an Object I created. Here's the relevant portion of my .yaml file:

components:
  schemas:
    Dummy:
      type: object
      properties:
        iMinMax:
          type: integer
          format: int32
          minimum: 0
          maximum: 100
        dMinMaxEx:
          type: number
          format: int32
          minimum: 5.0
          maximum: 10.0
          exclusiveMinimum: false
          exclusiveMaximum: true
        dMinExMaxEx:
          type: number
          format: int32
          minimum: 5.0
          maximum: 10.0
          exclusiveMinimum: true
          exclusiveMaximum: true
        dMinExMax:
          type: number
          format: int32
          minimum: 5.0
          maximum: 10.0
          exclusiveMinimum: true
          exclusiveMaximum: false
        sArray:
          type: array
          items:
            type: string
          minItems: 5
          maxItems: 10
          uniqueItems: true
        sLen:
          type: string
          format: text
          minLength: 5
          maxLength: 10

I turned on the bean validation option of the Spring code generator and generated server code, but it didn't have any effect. The code it generated was exactly the same as with the option turned off. Does anyone know how to use Swagger's Bean Validation option?

Give a look to this https://www.vojtechruzicka.com/documenting-spring-boot-rest-api-swagger-springfox/, it seems that JSR-303 is not working OOB — Raffaele, Dec 06 '18 at 15:18
Thank you for the link. It clarified a few things, but I'm still confused. It talks about annotations in my model classes. But in my experience, it doesn't read my model classes. Is it talking about annotations that I add to the models that swagger generates? Or is there some other setting that tells it to read my Hibernate databeans? — MiguelMunoz, Dec 09 '18 at 09:46

score 17 · Answer 1 · edited Apr 30 '21 at 07:10

There are 2 properties that influence bean validation within the latest version of the generator (3.3.4 last I checked). These properties are performBeanValidation and useBeanValidation (both false by default). To understand how they work you should look at the mustache templates that the generator uses in conjunction with the generator properties. These can be found in the JavaSpring Mustache files.

For example, you will see different behavior with and without performBeanValidation if your API yaml contains an attribute defined with format: email. With performBeanValidation=true the generator outputs an @Email validation annotation. With performBeanValidation=false you will not see this annotation. This can be understood by looking at the following mustache file: beanValidationCore

You can override any of these Mustache templates by copying the original Mustache file from the source location to your own project location and modify it as required. You then supply the project location as a parameter or property to the generator. e.g templateDirectory=src/main/resources/mustache

Blockquote

        <plugin>
            <groupId>org.openapitools</groupId>
            <artifactId>openapi-generator-maven-plugin</artifactId>
            <version>${openapi-codegen-version}</version>
            <executions>
                <execution>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                    <configuration>
                        <inputSpec>api.yaml</inputSpec>
                        <output>target/generated-sources</output>
                        <apiPackage>my.package.api</apiPackage>
                        <modelPackage>my.package.api.model</modelPackage>
                        <generatorName>spring</generatorName>
                        <templateDirectory>src/main/resources/mustache</templateDirectory>
                        <!--<configHelp>true</configHelp>-->
                        <!--<verbose>true</verbose>-->
                        <configOptions>
                            <dateLibrary>java8-localdatetime</dateLibrary>
                            <java8>false</java8>
                            <interfaceOnly>true</interfaceOnly>
                            <performBeanValidation>true</performBeanValidation>
                            <useBeanValidation>true</useBeanValidation>
                        </configOptions>
                    </configuration>
                </execution>
            </executions>
        </plugin>

Just adding, in order to add a custom bean validation it is needed to use the prefix "#vendorExtensions" on mustache template e.g {{#vendorExtensions.x-customValidation}}@com.my.CustomValidation{{/vendorExtensions.x-customValidation}} — Edy Segura, Aug 20 '20 at 12:50
Thank you, this is helpful. But I was hoping for some page in their documentation that explains how to use it. I don't want to have to learn how to read a .mustache file just to find out what a configuration property is for. Isn't this documented somewhere? (I can't find it.) — MiguelMunoz, Mar 11 '21 at 04:28
Not documented to my knowledge. Part of the description in https://github.com/OpenAPITools/openapi-generator/issues/5637 is in line with your comment. — Marcel Stör, Apr 30 '21 at 06:52
"To understand how they work you should look at the mustache templates" - no, I should be able to find the behavior described in the documentation :-/ — Marcel Stör, Apr 30 '21 at 06:53
I did find some documentation at https://github.com/OpenAPITools/openapi-generator/blob/master/docs/generators/spring.md. For `useBeanValidation` it says "Use BeanValidation API annotations," and for `performBeanValidation` it says "Use Bean Validation Impl. to perform BeanValidation." But when I generate the code, it doesn't matter what I set for these options. The generated code is the same, so I'm still wondering how I can use them. — MiguelMunoz, May 24 '22 at 08:57
you must pass these like this: ` --additional-properties=performBeanValidation=true` `--additional-properties=useBeanValidation=true` — mhrsalehi, Sep 09 '22 at 19:40

How can I use the useBeanValidation option when generating code in Swagger?

1 Answers1