資訊平台: 2022

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:

https://springdoc.org/v2/

資訊平台

Spring boot 3 OpenApi 2.0

網頁