Possibility to specify custom schema examples.

[ptahchiev]

Here's my situation:

• We are building a a REST API and we want to document it with SpringDoc/Swagger
• Some of the APIs return ProductDto which is defined in a jar file and we have no access to the codebase of ProductDto.
• The ProductDto has a field of type MonetaryAmount and we have registered a jackson module to deal with serialization/de-serialization of MonetaryAmount. So when the API is invoked we see this in the response:

  "price": {
    "amount": "5.00",
    "currency": "USD"
  },

however, the Swagger-UI and the generated schema shows this as an example:

    "price": {
      "code": "string",
      "defaultPaymentInfo": true,
      "subscriptionCode": "string",
      "saved": true,
      "paymentMode": {
        "id": "string",
        "code": "string",
        "name": "string",
        "description": "string",
        "method": {},
        "hopChargeUrl": "string",
        "cost": {
          "negativeOrZero": true,
          "positiveOrZero": true,
          "negative": true,
          "zero": true,
          "positive": true,
          "context": {
            "precision": 0,
            "fixedScale": true,
            "maxScale": 0,
            "empty": true,
            "providerName": "string"
          },
          "currency": {
            "defaultFractionDigits": 0,
            "numericCode": 0,
            "currencyCode": "string",
            "context": {
              "empty": true,
              "providerName": "string"
            }
          },
          "number": {
            "amountFractionNumerator": 0,
            "amountFractionDenominator": 0,
            "precision": 0,
            "scale": 0
          }
        }
      },

Is there a possibility to register something like SchemaCustomizer to provide custom snippet for fields of type MonetaryAmount?
We can't add annotations because we don't have access to the source-code and my wish was to actually deal with this in a central place, rather than going through all of our DTOs and adding custom annotations every time I see a field of type MonetaryAmount.

[bnasslahsen]

Hello,

If we suppose, you are using this custom class for Schema mapping:

public class CustomMonetaryAmount {

	@JsonProperty("amount")
	BigDecimal amount;

	@JsonProperty("currency")
	String currency;

}

You can then call:

static {
 SpringDocUtils.getConfig().replaceWithClass(MonetaryAmount.class, CustomMonetaryAmount.class);
}

[ptahchiev]

Hi @bnasslahsen maybe I'm doing something wrong but the replaceWithSchema method requires an object of type Schema and the the CustomMonetaryAmount class you have given is not a Schema :(

[bnasslahsen]

I have edited my comment to replaceWithClass.
Can you tell if its working in your case?

[ptahchiev]

I added this:

    @Bean
    public OpenApiCustomiser defaultOpenApiCustomizer() {
        return openApi -> SpringDocUtils.getConfig().replaceWithClass(MonetaryAmount.class, CustomMonetaryAmount.class);
    }

    public class CustomMonetaryAmount {
        @JsonProperty("amount")
        private BigDecimal amount;

        @JsonProperty("currency")
        private String currency;

    }

but when I access the swagger I get this:

 2020-02-26 17:55:23,482 org.apache.catalina.core.ContainerBase.[Tomcat].[localhost].[/storefront].[dispatcherServlet] [https-jsse-nio-127.0.0.1-8112-exec-8] ERROR: Servlet.service() for servlet [dispatcherServlet] in context with path [/storefront] threw exception [Request processing failed; nested exception is java.lang.IllegalArgumentException: Conflicting setter definitions for property "number": javax.money.MonetaryAmountFactory#setNumber(1 params) vs javax.money.MonetaryAmountFactory#setNumber(1 params)] with root cause
java.lang.IllegalArgumentException: Conflicting setter definitions for property "number": javax.money.MonetaryAmountFactory#setNumber(1 params) vs javax.money.MonetaryAmountFactory#setNumber(1 params)
	at com.fasterxml.jackson.databind.introspect.POJOPropertyBuilder.getSetter(POJOPropertyBuilder.java:497)
	at com.fasterxml.jackson.databind.introspect.BeanPropertyDefinition.getMutator(BeanPropertyDefinition.java:203)
	at com.fasterxml.jackson.databind.introspect.POJOPropertyBuilder.getPrimaryMember(POJOPropertyBuilder.java:571)
	at io.swagger.v3.core.jackson.ModelResolver.resolve(ModelResolver.java:542)
	at org.springdoc.core.converters.AdditionalModelsConverter.resolve(AdditionalModelsConverter.java:49)

[bnasslahsen]

@ptahchiev,

You don't need to declare replaceWithClass using OpenApiCustomiser .
Its better to declare it in static block, once yout application is started.
Please have a look at my updated sample code provided, and tell us if its working for you.

[ptahchiev]

Hi @bnasslahsen it works with a static block, and it also works using an OpenApiBuilderCustomizer - one more reason for #451 to go in :))

[AnthonyGress]

@bnasslahsen How do you use SpringDocUtils? I don't see it as an import and can't find anything in the docs or online about how to use it, other than that same code snippet.

[bnasslahsen]

@AnthonyGress,

it's all documented here:

• https://springdoc.org/

And for concrete java samples, search for SpringDocUtils in this repo.