Could `@Schema(nullable = true)` work when outputting OpenAPI 3.1.0?

[karlvr]

Due to the removal of nullable: true from schema in 3.1.0, it appears that the nullable = true property on the @Schema annotation no longer works. That isn't obvious in the documentation for the annotation, and it's inconvenient to boot ;-)

I think it will be quite easy to continue to support the nullable attribute under 3.1.0, I suggest a little change to Schema.getTypes:

    @OpenAPI31
    public Set<String> getTypes() {
        if (types != null) {
            if (nullable != null && nullable.booleanValue()) {
                Set<String> ss = new LinkedHashSet<>(types);
                ss.add("null");
                return ss;
            } else {
                return types;
            }
        } else {
            return null;
        }
    }

We simply add "null" to the list of types if the schema is nullable... which ends up nicely in the schema output.

I'm happy to make a PR of this, or a better suggestion, or I'd love to know if this is more like the wrong approach!

[karlvr]

Ugh, nullable properties that use a $ref aren't that simple... it seems they need to transform into:

allOf:
  - $ref: '#/...'
  - { type: "null" }

Heh, I'm not immediately a fan of OpenAPI 3.1 :-D

Instead I've solved this with a filter. If you, the maintainers, think that support for Schema.nullable is nice for OpenAPI 3.1 support, I'd be happy to work on a PR, otherwise I'll leave this filter here for anyone else in this predicament to enjoy and please close this issue!

import java.util.List;
import java.util.Map;
import java.util.Optional;

import io.swagger.v3.core.filter.AbstractSpecFilter;
import io.swagger.v3.core.util.AnnotationsUtils;
import io.swagger.v3.oas.models.SpecVersion;
import io.swagger.v3.oas.models.media.Schema;

/**
 * A filter to add support for {@link Schema#getNullable()} under OpenAPI 3.1.0. As of swagger-core 2.2.19 that property
 * is ignored when serializing to OpenAPI 3.1.0. This filter modifies property schemas to translate nullable to
 * OpenAPI 3.1.0.
 * <p>
 * OpenAPI 3.1.0 doesn't directly support {@code nullable} anymore; instead we must add {@code null} to the array of types.
 */
public class NullableToOpenAPI31Filter extends AbstractSpecFilter {

	@Override
	public Optional<Schema> filterSchemaProperty(Schema property, Schema schema, String propName,
			Map<String, List<String>> params, Map<String, String> cookies, Map<String, List<String>> headers) {
		if (property.getNullable() != null && property.getNullable().booleanValue()) {
			if (property.get$ref() != null) {
				Schema clone = AnnotationsUtils.clone(property, isOpenAPI31Filter());

				clone.$ref(null);
				
				clone.addAnyOfItem(new Schema(property.getSpecVersion()).$ref(property.get$ref()));
				clone.addAnyOfItem(new NullSchema(property.getSpecVersion()));

				return Optional.of(clone);
			} else {
				Schema clone = AnnotationsUtils.clone(property, isOpenAPI31Filter());
				if (!clone.getTypes().contains("null")) {
					clone.addType("null");
				}
				return Optional.of(clone);
			}
		} else {
			return super.filterSchemaProperty(property, schema, propName, params, cookies, headers);
		}
	}
	
	@Override
	public boolean isOpenAPI31Filter() {
		return true;
	}

	public static class NullSchema extends Schema {

		public NullSchema(SpecVersion specVersion) {
			super("null", null, specVersion);
		}

	}
	
}

[zeldigas]

@karlvr how do you apply this filter?

[karlvr]

@zeldigas sorry for the slow reply, like this in my class that extends javax.ws.rs.core.Application:

OpenAPI oas = new OpenAPI();
...
SwaggerConfiguration oasConfig = new SwaggerConfiguration();
oasConfig.setOpenAPI(oas);
oasConfig.openAPI31(true); /* Required so that descriptions on properties that turn into $refs stay on the property */
oasConfig.setFilterClass(NullableToOpenAPI31Filter.class.getName());

try {
	new JaxrsOpenApiContextBuilder()
			.servletConfig(servletConfig)
			.application(this)
			.openApiConfiguration(oasConfig)
			.buildContext(true);
} catch (OpenApiConfigurationException e) {
	throw new RuntimeException(e.getMessage(), e);
}

[squinker]

Does the Schema annotation have the capability to express this yet?

allOf:
  - $ref: '#/...'
  - { type: "null" }

[ewaostrowska]

Hi! This issues should be resolved with #5018 and it will be part of the next release :)