resolve-schema-properties is not replacing tokens from properties file

[nigelsim]

Describe the bug
I am migrating from SpringFox to SpringDoc, using org.springdoc:springdoc-openapi-webmvc-core:1.6.6.

All of my property descriptions are in a properties file that is used in the Schema using ${Model.property}. In SpringFox this was @ApiModelProperty(value = "${Generic.name}"), and in SpringDoc this is @Schema(description = "${Generic.name}").

Following the FAQ I set springdoc.api-docs.resolve-schema-properties: true, however, I still get the unresolved tokens in the output. (Also, looking at the code I can't see where this config parameter is used).

Debugging, I can see that the MessageConverter being passed into PropertyResolverUtils is an empty message converter.

I am running SpringDoc from within an test, which is how I used to run SpringFox. This has tended to be more reliable, and quicker, than starting a background copy of the app like the Gradle/Maven plugin does.

To Reproduce

application.properties

springdoc:
  api-docs:
    enabled: true
    resolve-schema-properties: true

DTO

@Data
public class PersonDto {
    @Schema(description = "${Generic.id}", required = true)
    private Long id;
}

swagger-messages.properties

Generic.id=The database ID for this entity instance

Code generation test

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.MOCK, classes = PortalApplication.class)
@PropertySources({@PropertySource("classpath:swagger-messages.properties"),
        @PropertySource("classpath:version.properties")})
@AutoConfigureMockMvc
@Import(UpdateSwaggerModels.SwaggerConfiguration.class)
@WithMockUser
public class UpdateSwaggerModels {
    @TestConfiguration()
    public static class SwaggerConfiguration {
        @Bean
        public GroupedOpenApi externalApi() {
            return GroupedOpenApi.builder()
                    .group("default")
                    .packagesToScan("io.portal.web.extapi")
                    .build();
        }

    @Autowired
    private MockMvc mockMvc;

    @Autowired
    private List<GroupedOpenApi> groupList;

    @Tag("OpenAPI")
    @Test
    public void generateOpenApi() throws Exception {
        for (GroupedOpenApi group : groupList) {
            File outputFile = new File("api-" + group.getGroup() + ".json");
            try (FileWriter w = new FileWriter(outputFile)) {
                this.mockMvc.perform(get("/v3/api-docs/" + group.getGroup()).accept(MediaType.APPLICATION_JSON))
                        .andDo(result -> w.write(result.getResponse().getContentAsString()))
                        .andExpect(status().isOk());
            }
        }
    }

}

Expected behavior

• Tokens to be replaced with text from the property

[bnasslahsen]

See sample Test here, which working perfectly.

[nigelsim]

Hi @bnasslahsen thank you for the pointer to the test case.

This works as expected if you fetch the root api docs URL (/v3/api-docs) as it does in the unit test. This works in my code too if I change the generate code to

    public void generateSwagger() throws Exception {
            File outputFile = new File("api.json");
            try (FileWriter w = new FileWriter(outputFile)) {
                this.mockMvc.perform(get("/v3/api-docs").accept(MediaType.APPLICATION_JSON))
                        .andDo(result -> w.write(result.getResponse().getContentAsString()))
                        .andExpect(status().isOk());
            }
    }

But, if I try to fetch a specific group using the url /v3/api-docs/GROUP then the customiser is not applied. I've confirmed this by putting a breakpoint in SpringDocConfiguration.java:343 and see that the lambda is returned by never called.

Is there any further configuration I require to make this work?

[bnasslahsen]

@nigelsim,

Yes, for groups you might should attach the appropriate customizers.
This is a sample code, that you can adapt:

	@Bean
	public GroupedOpenApi testGroup(OpenAPIService openAPIService) {
		String[] paths = { "/tweets/**" };
		return GroupedOpenApi.builder().
				group("tweets")
				.addOpenApiCustomiser(openApi -> propertiesResolverForSchema(openAPIService))
				.pathsToMatch(paths)
				.build();
	}

	OpenApiCustomiser propertiesResolverForSchema(OpenAPIService openAPIService) {
		return openApi -> {
			Components components = openApi.getComponents();
			Map<String, Schema> schemas = components.getSchemas();
			if (!CollectionUtils.isEmpty(schemas))
				schemas.values().forEach(schema -> openAPIService.resolveProperties(schema, Locale.getDefault()));
		};
	}

We might put propertiesResolverForSchema public for the futur so you can reuse it.

[nigelsim]

Thanks, all working now, but just there was a missing call in the customisation.

	@Bean
	public GroupedOpenApi testGroup(OpenAPIService openAPIService) {
		String[] paths = { "/tweets/**" };
		return GroupedOpenApi.builder().
				group("tweets")
				.addOpenApiCustomiser(openApi -> propertiesResolverForSchema(openAPIService).customise(openApi))
				.pathsToMatch(paths)
				.build();
	}

My final implementation uses the customiser from the context (as I saw demonstrated in app68 from the tests). This of course requires the property to be set true so the bean exists

        @Bean
        public GroupedOpenApi testGroup(@Qualifier("propertiesResolverForSchema") OpenApiCustomiser propertiesResolverForSchema) {
		String[] paths = { "/tweets/**" };
		return GroupedOpenApi.builder()
				.group("tweets")
                                .addOpenApiCustomiser(propertiesResolverForSchema)
				.pathsToMatch(paths)
				.build();
        }

I would suggest that the expected behaviour when configuring group-configs via the properties is that the configuration such as resolve-schema-properties would apply to them, especially given you can't provide per-group configuration of these.

I get that if you are configuring via code then building these by hand is probably preferable, as the main reason you'd do this via code is to have more control.

[bnasslahsen]

@nigelsim,

I have added a new enhancement, to handle this case out of the box.
Feel free to test with the latest SNAPSHOT and provide your feedback.

[nigelsim]

Thanks, works well. I look forward to the next release.