В июле 2020 года был выпущен Springfox 3.0, поддерживающий OAS 3.0.
Интегрируйте Springfox 3.0
Springfox 3.0 имеет несколько модулей и обеспечивает стартер загрузки Spring.При интеграции со Spring Boot необходимо ввести только springfox-boot-starter, а именно:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
Если вы раньше использовали Springfox 2.x, вам необходимо изменить конфигурацию Swagger:
- Удалите аннотацию @ EnableSwagger2 и измените ее на @EnableOpenApi.
- Измените параметр DocumentationType.SWAGGER_2 в Docket на DocumentationType.OAS_30
- Springfox 3.0 удаляет некоторые сторонние модули, если какие-либо ссылки необходимо заменить
Измененная конфигурация выглядит следующим образом:
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));
}
}
Выше мы использовали HttpAuthenticationScheme для создания аутентификации токена-носителя и вывода значения токена непосредственно при нажатии кнопки «Авторизовать» в интерфейсе пользовательского интерфейса Swagger.
Адрес пользовательского интерфейса Swagger в Springfox 3.0 был изменен с http: //host/context-path/swagger-ui.html на http: // host / context-path / swagger-ui / . Адрес api docs OAS 3.0 по умолчанию v3 / api-docs, поэтому необходимо соответствующим образом изменить путь игнорирования в Security.
Параметры страницы
Когда метод REST API содержит параметры org.springframework.data.domain.Pageable, Springfox генерирует pageNumber, pageSize, offset, paged, unpaged, sort.sorted, sort.unsorted и другие параметры в соответствии с интерфейсом, которые совпадают с параметрами, фактически используемыми Spring Boot. Непоследовательно, поэтому для параметров Pageable требуется специальная обработка.
Мы используем OperationBuilderPlugin для обработки параметров Pageable, как показано ниже:
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;
}
}
Параметры страницы, отображаемые в пользовательском интерфейсе Swagger после модификации, следующие:
В новых проектах также можно использовать springdoc-openapi . Проект был создан в июле 2019 года и имеет высокую частоту обновлений. На данный момент выпущено несколько версий. Последняя версия - v1.5.0. Документация springdoc-openapi очень исчерпывающая и понятная по структуре, а также рекомендуется документация по миграции на springfox.
Справка
Спецификация OpenAPI
springdoc-openapi
GitHub Springfox GitHub
springdoc-openapi