Spring Boot 3 Using SpringDoc OpenApi 2.0.0-M5
在Spring boot 3 版本需要使用Swagger 時，如果使用 io.springfox 是無法使用，因未支援Spring boot 3版本號，目前只支援到Spring boo 2.x版本 ，而Spring boot 3要使用Swagger 的話，需要使用io.springdoc OpenApi 2.x版本，目前opena 在maven上只能找到1.6.11版本 ，無法找到2.0版本 , 2.0版是另外查詢的，OpenApi 2.0。
新增pom.xml library ${com.swagger.spring.boot.V3.version}= 2.0.0.M5
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>${com.swagger.spring.boot.V3.version}</version>
</dependency>
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
<version>${com.swagger.spring.boot.V3.version}</version>
</dependency>
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-common</artifactId>
<version>${com.swagger.spring.boot.V3.version}</version>
</dependency>
建立Swagger.java
透過@Configuartion 標注，提供Spring載入設定
新增在Swagger 預設的header參數，例如token , user , version之類，設定Swagger , 類分
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import io.swagger.v3.oas.models.*;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.media.NumberSchema;
import io.swagger.v3.oas.models.media.StringSchema;
import io.swagger.v3.oas.models.parameters.Parameter;
import org.springdoc.core.customizers.OperationCustomizer;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.method.HandlerMethod;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import java.util.ArrayList;
import java.util.List;
/**
* @author neillin
* @since 2022/10/02 - 9:34 AM
*/
@Configuration
@EnableWebMvc
public class SwaggerConfig {
@Value("${app.version}")
private String apVersion;
/**
* default Parameters "X-Auth-Token","userId","version" header 參數
* @return List<OperationCustomizer>
*/
private List<OperationCustomizer> setDefaultHeader(){
List<OperationCustomizer> operationCustomizers = new ArrayList<>();
//default header type
String[] header = {"X-Auth-Token","userId","version"};
String[] headerName = {"授權驗証","user_id","版本號"};
for (int i = 0; i < header.length; i++) {
String setHeader = header[i];
String setHeaderName = headerName[i];
OperationCustomizer operationCustomizer = new OperationCustomizer() {
@Override
public Operation customize(Operation operation, HandlerMethod handlerMethod) {
Parameter customHeaderVersion = new Parameter();
if(setHeader.equals("userId")) {
customHeaderVersion.in(ParameterIn.HEADER.toString())
.name(setHeader)
.description(setHeaderName)
.schema(new NumberSchema()) //long
.required(false);
} else {
customHeaderVersion.in(ParameterIn.HEADER.toString())
.name(setHeader)
.description(setHeaderName)
.schema(new StringSchema()) //string
.required(false);
}
operation.addParametersItem(customHeaderVersion);
return operation;
}
};
operationCustomizers.add(operationCustomizer);
}
return operationCustomizers;
}
/**
* @return GroupedOpenApi
*/
@Bean
public GroupedOpenApi publicApi() {
return GroupedOpenApi.builder()
.group("OpenApi") //顯示在Select a definition 可以分層，
.pathsToMatch("/**") //全部 controller
.build()
.addAllOperationCustomizer(this.setDefaultHeader());
}
@Bean
public OpenAPI springShopOpenAPI(){
return new OpenAPI()
.components(new Components())
.info(new Info()
.title("OpenApi-API服務")
.version(apVersion)
.description("API服務"))
.externalDocs(new ExternalDocumentation()
.description("Spring-boot v3 + OpenAPI 3")
.url("https://springdoc.org/v2") );
}
}
在Controller 加入Swagger, 實做每一個Api標題 (可參考官方網站)
如果使用SpringFox Swagger 與SpringDoc OpenApi的 Annotations,需要調整
@Api → @Tag
@ApiIgnore → @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
@ApiImplicitParam → @Parameter
@ApiImplicitParams → @Parameters
@ApiModel → @Schema
@ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)
@ApiModelProperty → @Schema
@ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")
@ApiParam → @Parameter
@ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")@RestController
@RequestMapping("/api")
@Slf4j
@Tag(name = "api", description = "測試")
public class TestController {
@Resource
private TestDBService testDBService;
@Operation(summary = "測試db data", description = "測試es ",parameters = {@Parameter(name = "userId" , description = "用戶id")})
@ApiResponse(responseCode = "2xx" , description = "成功")
@GetMapping(value = "/db/{userId}" , produces = APPLICATION_JSON_VALUE)
public Object getDB(@PathVariable Long userId){
Object data = testDBService.findByUserId(userId);
return success(data);
}
Swagger Ui default 為swagger-ui.html , 也是可以自行定義需要的名稱。
開啟Swagger 網址 http://localhost:8080/swagger-ui.html 就會出現下面畫面，可以看到剛剛設定的X-Auth-Token header及api所需要帶入的參數。
Github:
https://github.com/neiltw/springboot3-openapi-2.0
References:
