Springfox has finally made a Spring Boot Starter for Swagger, and it looks like my own Swagger Starter will be retired soon.

Why didn’t the corresponding Spring Boot Starter come out officially before

When I first encountered Spring Boot, I was wondering why Swgger, a popular documentation framework, didn’t have its own Spring Boot Starter. Later, for my own convenience, I masturbated a set of starter for my own use. At that time, I also understood how Spring Boot was configured automatically, and the configuration prompts in the configuration files were which files to read. In the process of lstarter, it is also found that the object creation in Swagger is basically using the Builder constructor mode, such as creating the ApiInfo through the ApiInfoBuilder:

public class ApiInfoBuilder { ...... public ApiInfo build() { return new ApiInfo(title, description, version, termsOfServiceUrl, contact, license, licenseUrl, vendorExtensions); }}Copy the code

There are no setters in the ApiInfo class. Properties are set via constructors:

public class ApiInfo { ...... public ApiInfo(......) {... }... }Copy the code

As you know, there are two common ways to set Java properties: constructors and setter methods. A framework as generic as Spring Boot is bound to use the most generic approach to get the broadest framework compatibility: find the appropriate setter method through the property name of the configuration file and do property injection. However, Swagger’s attribute setting in Builder mode is naturally incompatible, because Spring Boot has read the configuration attribute and cannot find the corresponding setter method. If Swagger wants to be compatible with Spring Boot, there are mainly the following two ways:

  1. Official: Change the Builder mode setting property to setter
  2. Unofficial way: Create a new property configuration class and then create a Bean into the container, like the Swagger Starter I wrote a while ago, for example:
@Setter @ToString public class ApiInfoProperties { private String version; private String title; private String description; private String termsOfServiceUrl; private String license; private String licenseUrl; private ContactProperties contact = new ContactProperties(); ApiInfo toApiInfo() { return new ApiInfo(title, description, version, termsOfServiceUrl, contact.toContact(), license, licenseUrl, Collections.emptyList()); }}Copy the code

Currently, the official Swagger Starter only supports properties for basic features, Some automatic configurations like path-selector, global-parameters, security-schema, security-Context have not been implemented yet. However, springFox’s selection of Spring Boot compatible methods will be official if not unexpected, that is, to change the Builder to setter. Here is a summary of the current official starter configuration classes:

@ConfigurationProperties("springfox.documentation") public class SpringfoxConfigurationProperties { private boolean autoStartup = true; private boolean enabled = true; @NestedConfigurationProperty private SwaggerConfigurationProperties swagger; @NestedConfigurationProperty private OpenApiConfigurationProperties openApi; @NestedConfigurationProperty private SwaggerUiConfigurationProperties swaggerUi; public boolean isAutoStartup() { return autoStartup; } public void setAutoStartup(boolean autoStartup) { this.autoStartup = autoStartup; }... }Copy the code

What improvements Swagger 3.0 has made

Specific improvements can be viewed in the official document, and I will simply list a few that I think are important:

  • Webflux is supported by Swagger 3.0, but postman is not supported by Swagger 3.0
  • Remove the third party dependency libraries, such as Guava, which I personally consider to be more disreputable in the previous version, because these dependency libraries will lead to duplication in most projects
  • addedspringfox-boot-starter, can support traditional Web and responsive WebFlux, currently only provides simple functionality
  • removed@EnableSwagger2Annotations, which simplify configuration, change the document address, and are currently accessible only by introducing the starter dependency running projecthttp://host:port/{context-path}/swagger-ui/Viewing interface Documentation

Quick start

Add the dependent

< the dependency > < groupId > IO. Springfox < / groupId > < artifactId > springfox - the boot - starter < / artifactId > < version > 3.0.0 < / version > </dependency>Copy the code

Start project access Swagger address

Starter does not support ApiInfo, SecurityContext, etc. For more examples of project configuration (e.g. Webflux), please refer to the official swagger starter example. The Swagger starter configuration is prefixed with Springfox. documentation, which can be found in the configuration file.

The resources

Official documentation: github.com/springfox/s… Official example: github.com/springfox/s…