Swagger 2 using Springfox (Spring Boot)
Introduction
Swagger allows you to describe the structure of your APIs so that machines can read them.
As of 2019-dec, Springfox is abandoned (not compatible with Spring Boot 2.2).
An alternative is springdoc-openapi [https://stackoverflow.com/questions/58626347/springfox-swagger-not-working-in-spring-boot-2-2-0].
Reference for springdoc-openapi (OpenAPI 3) [https://github.com/springdoc/springdoc-openapi]
Warning: 'openapi-generator-maven-plugin' as of version 4.2.2 generated sources with Springfox annotation. As of version 5.0.0 the project has moved to springdoc.
References
Setting Up Swagger 2 with a Spring REST API
http://www.baeldung.com/swagger-2-documentation-for-spring-rest-api
Configuration
Restrict swagger generation to a specific package and paths:
package edu.cou.doc;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* Swagger 2 config.<br>
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2).select()
.apis(RequestHandlerSelectors.basePackage("edu.cou.doc.rest"))
// Exclude paths starting with '/tech' or '/test*'
.paths(PathSelectors.regex("(?!/tech).+")).paths(PathSelectors.regex("(?!/test).+"))
.build();
}
}
Enable Authorization Bearer token
Add to SwaggerConfig the securitySchemes, eg:
import java.util.ArrayList;
import org.springframework.boot.autoconfigure.condition.ConditionalOnExpression;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import com.google.common.base.Predicates;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.SecurityScheme;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@ConditionalOnExpression("'${env}' != 'pre' or '${env}' != 'pro'")
@EnableSwagger2
public class SwaggerConfig {
@Bean
Docket api() {
return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.any())
.paths(Predicates.not(PathSelectors.regex("/login.*|/error.*"))).build()//
.securitySchemes(securitySchemes());
}
private static ArrayList<? extends SecurityScheme> securitySchemes() {
ArrayList<ApiKey> ret = new ArrayList<>();
ret.add(new ApiKey("Bearer", "Authorization", "header"));
return ret;
}
}
And to the controller operation the @ApiOperation annotation with the authorizations attribute:
@ApiOperation(value = "Get equipments by id", authorizations = @Authorization(value = "Bearer"))
@GetMapping(value = "/{id}", produces = { MediaType.APPLICATION_JSON_VALUE })