Springfox Additional Models Support

[Larkenx]

A key feature offered by Springfox that was very appealing for reverse-engineering/retrofitting an existing Spring Boot microservice to generate an OAS was the ability to ad-hoc pick up POJOs and have a schema generated for it.

This was done using .additionalModels(typeResolver.resolve(AdditionalModel.class)); in the builder pattern for the Docket. See https://springfox.github.io/springfox/docs/snapshot/#springfox-spring-mvc-and-spring-boot example 24 for a hands on example, but this was extremely convenient as it would generate the schema/component definitions for me for deeply nested objects.

Is there already support for this? If so, it would be a great add to FAQ.

[bnasslahsen]

Hi @Larkenx,

Lets suppose you have the follwing controller:

@RestController
public class HelloController {

	@GetMapping(value = "/users")
	public String getUser(User user) {
		return "user";
	}
}

public class User {

	@JsonProperty("id")
	private String id;

	@JsonProperty("name")
	private String name;

	@JsonProperty("pwd")
	private String pwd;

}

And you want to replace in the generated Schema, the User class schema befintion, by another one, lets say User 2:

@Schema(name = "User")
public class User2 {

	@JsonProperty("name2")
	private String name2;
}

To achive this, you can define your own OpenApiCustomiser, as follow:

@Bean
public OpenApiCustomiser schemaCustomiser() {
	ResolvedSchema resolvedSchema = ModelConverters.getInstance()
			.resolveAsResolvedSchema(new AnnotatedType(User2.class));
	return openApi -> openApi
			.schema(resolvedSchema.schema.getName(), resolvedSchema.schema);
}

Also, note that if your addtional model is not referenced, springdoc-openapi removes every broken reference definitions.

Let us know, if this answers your question.

[Larkenx]

While this definitely works if you want to annotate every individual POJO and controller, my use case differed a bit from the approach above. I wanted to simply generate the Open API spec yaml/json as a baseline with the existing Spring Boot controllers, but then manually write up summaries, descriptions, response types, and return types in the yaml itself.

Springfox allows you to generate the models without associating them or referencing them explicitly in your controllers, and that's what I found valuable since I wanted to manually do that process.

What you shared above defnitely works, but this would force me to actually implement placing the annotations on all the various controllers / POJOs. My primary use case here is for large existing microservices that weren't built-out with an Open API or API driven development mindset.

Do you have any suggestions on better ways to go back and reverse engineering Open API specs from existing services? I'm not opposed to making it mandatory to go back and annotate old projects, but that may or may not be more effort than doing the approach I described above.

(Also, the return types of our controllers are almost always Strings because we serialize manually with GSON as opposed to Jackson w/ Spring, but I think swagger-core provides annotations that resolve this anyway)

[bnasslahsen]

With OpenApiCustomiser , you have access to the OpenAPI Object.
You can add any object/operation you want without having to add annotations on your code.
Please have a look at the documentation and our contribution guide.
And if its not enough, get back to us with a concrete example of the limitation you are facing, and we will be happy to help.