En julio de 2020, se lanzó Springfox 3.0, compatible con OAS 3.0.
Integrar Springfox 3.0
Springfox 3.0 tiene varios módulos y proporciona un iniciador de arranque de primavera. Cuando se integra con Spring Boot, solo es necesario introducir springfox-boot-starter, de la siguiente manera:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>Si ha utilizado Springfox 2.x antes, debe modificar la configuración de Swagger:
- Elimine la anotación @ EnableSwagger2 y cámbiela a @EnableOpenApi
- Cambie el parámetro DocumentationType.SWAGGER_2 en Docket a DocumentationType.OAS_30
- Springfox 3.0 elimina algunos módulos de terceros, si es necesario reemplazar alguna referencia
La configuración modificada es la siguiente:
import com.fasterxml.classmate.TypeResolver;
import org.itrunner.heroes.exception.ErrorMessage;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.ResponseEntity;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import java.time.LocalDate;
import java.util.List;
import static java.util.List.of;
@EnableOpenApi
@Configuration
public class SwaggerConfig {
@Bean
public Docket petApi() {
return new Docket(DocumentationType.OAS_30)
.select()
.apis(RequestHandlerSelectors.basePackage("org.itrunner.heroes.controller"))
.paths(PathSelectors.any())
.build()
.apiInfo(apiInfo())
.pathMapping("/")
.directModelSubstitute(LocalDate.class, String.class)
.genericModelSubstitutes(ResponseEntity.class)
.additionalModels(new TypeResolver().resolve(ErrorMessage.class))
.useDefaultResponseMessages(false)
.securitySchemes(of(authenticationScheme()))
.securityContexts(of(securityContext()))
.enableUrlTemplating(false);
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Hero Api Documentation")
.description("Hero Api Documentation")
.contact(new Contact("Jason", "https://blog.51cto.com/7308310", "[email protected]"))
.version("1.0.0")
.build();
}
private HttpAuthenticationScheme authenticationScheme() {
return HttpAuthenticationScheme.JWT_BEARER_BUILDER.name("BearerToken").build();
}
private SecurityContext securityContext() {
return SecurityContext.builder()
.securityReferences(defaultAuth())
.operationSelector(operationContext ->
operationContext.requestMappingPattern().startsWith("/api/")
)
.build();
}
private List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
return of(new SecurityReference("BearerToken", authorizationScopes));
}
}Anteriormente usamos HttpAuthenticationScheme para construir la Autenticación de token de portador y generar directamente el valor del token al hacer clic en Autorizar en la interfaz de IU de Swagger.
La dirección de la interfaz de usuario de Swagger de Springfox 3.0 se ha cambiado de http: //host/context-path/swagger-ui.html a http: // host / context-path / swagger-ui / . La dirección de documentos api de OAS 3.0 es / por defecto v3 / api-docs, por lo que la ruta de ignorar en Seguridad debe modificarse en consecuencia.
Parámetros paginables
Cuando el método de la API REST contiene org.springframework.data.domain.Pageable parámetros, Springfox genera pageNumber, pageSize, offset, paged, unpaged, sort.sorted, sort.unsorted y otros parámetros de acuerdo con la interfaz, que son los mismos que los parámetros realmente utilizados por Spring Boot Es inconsistente, por lo que se requiere un procesamiento especial para los parámetros paginable.
Usamos OperationBuilderPlugin para procesar parámetros paginable, de la siguiente manera:
package org.itrunner.heroes.config;
import com.fasterxml.classmate.ResolvedType;
import com.fasterxml.classmate.TypeResolver;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.core.annotation.Order;
import org.springframework.data.domain.Pageable;
import org.springframework.stereotype.Component;
import springfox.documentation.builders.RequestParameterBuilder;
import springfox.documentation.schema.ScalarType;
import springfox.documentation.service.ParameterType;
import springfox.documentation.service.RequestParameter;
import springfox.documentation.service.ResolvedMethodParameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.OperationBuilderPlugin;
import springfox.documentation.spi.service.contexts.OperationContext;
import java.util.ArrayList;
import java.util.List;
@Component
@Order
public class PageableParameterReader implements OperationBuilderPlugin {
private final TypeResolver resolver;
@Autowired
public PageableParameterReader(TypeResolver resolver) {
this.resolver = resolver;
}
@Override
public void apply(OperationContext context) {
List<ResolvedMethodParameter> methodParameters = context.getParameters();
ResolvedType pageableType = resolver.resolve(Pageable.class);
List<RequestParameter> parameters = new ArrayList<>();
for (ResolvedMethodParameter methodParameter : methodParameters) {
ResolvedType resolvedType = methodParameter.getParameterType();
if (pageableType.equals(resolvedType)) {
parameters.add(new RequestParameterBuilder()
.in(ParameterType.QUERY)
.name("page")
.query(q -> q.model(m -> m.scalarModel(ScalarType.INTEGER)))
.description("Results page you want to retrieve (0..N)").build());
parameters.add(new RequestParameterBuilder()
.in(ParameterType.QUERY)
.name("size")
.query(q -> q.model(m -> m.scalarModel(ScalarType.INTEGER)))
.description("Number of records per page").build());
parameters.add(new RequestParameterBuilder()
.in(ParameterType.QUERY)
.name("sort")
.query(q -> q.model(m -> m.collectionModel(c -> c.model(cm -> cm.scalarModel(ScalarType.STRING)))))
.description("Sorting criteria in the format: property(,asc|desc). "
+ "Default sort order is ascending. "
+ "Multiple sort criteria are supported.")
.build());
context.operationBuilder().requestParameters(parameters);
}
}
}
@Override
public boolean supports(DocumentationType delimiter) {
return true;
}
}Los parámetros paginable que se muestran en la interfaz de usuario de Swagger después de la modificación son los siguientes:
Los nuevos proyectos también pueden usar springdoc-openapi . El proyecto se creó en julio de 2019 y tiene una frecuencia de actualización relativamente alta. Hasta ahora se han lanzado varias versiones. La última versión es la v1.5.0. La documentación de springdoc-openapi es muy completa y clara en su estructura. También proporciona documentación de migración de Springfox, que se recomienda.
Referencia
Especificación de
OpenAPI springdoc-openapi
GitHub Springfox
GitHub springdoc-openapi