Swagger-ui 在查詢參數中展平對象，但生成的 Angular 客戶端不會

Question

我的 Spring Boot 應用程序中有以下 Rest 功能

@SecuredMaster
@GetMapping(path = "/mitarbeiter")
@Operation(security = {@SecurityRequirement(name = "jwt")})
public Page<MitarbeiterListRow> getMitarbeiter(Pageable pageable, @RequestParam(defaultValue = "") String query) {
    return mitarbeiterRepository.findAllByUsernameContainingIgnoreCaseOrEmailContainingIgnoreCase(pageable, query, query);
}

我使用 springdoc 生成 openapi3 yaml

// generate api docs
implementation 'org.springdoc:springdoc-openapi-ui:1.2.18'
implementation 'org.springdoc:springdoc-openapi-data-rest:1.2.18'

生成的 yaml 看起來像這樣

然后我生成一個角度客戶端

java -jar swagger-codegen-cli.jar generate -i http://localhost:8080/apidocs/v3/api-docs -l typescript-angular -o ../frontend/src/generated/swagger

生成的客戶端如下所示

/**
 * 
 * 
 * @param pageable 
 * @param query 
 * @param observe set whether or not to return the data Observable as the body, response or events. defaults to returning the body.
 * @param reportProgress flag to report request and response progress.
 */
public getMitarbeiter(pageable: Pageable, query?: string, observe?: 'body', reportProgress?: boolean): Observable<PageMitarbeiterListRow>;
public getMitarbeiter(pageable: Pageable, query?: string, observe?: 'response', reportProgress?: boolean): Observable<HttpResponse<PageMitarbeiterListRow>>;
public getMitarbeiter(pageable: Pageable, query?: string, observe?: 'events', reportProgress?: boolean): Observable<HttpEvent<PageMitarbeiterListRow>>;
public getMitarbeiter(pageable: Pageable, query?: string, observe: any = 'body', reportProgress: boolean = false ): Observable<any> {

    if (pageable === null || pageable === undefined) {
        throw new Error('Required parameter pageable was null or undefined when calling getMitarbeiter.');
    }


    let queryParameters = new HttpParams({encoder: new CustomHttpUrlEncodingCodec()});
    if (pageable !== undefined && pageable !== null) {
        queryParameters = queryParameters.set('pageable', <any>pageable);
    }
    if (query !== undefined && query !== null) {
        queryParameters = queryParameters.set('query', <any>query);
    }

    let headers = this.defaultHeaders;

    // authentication (jwt) required
    if (this.configuration.accessToken) {
        const accessToken = typeof this.configuration.accessToken === 'function'
            ? this.configuration.accessToken()
            : this.configuration.accessToken;
        headers = headers.set('Authorization', 'Bearer ' + accessToken);
    }
    // to determine the Accept header
    let httpHeaderAccepts: string[] = [
        '*/*'
    ];
    const httpHeaderAcceptSelected: string | undefined = this.configuration.selectHeaderAccept(httpHeaderAccepts);
    if (httpHeaderAcceptSelected != undefined) {
        headers = headers.set('Accept', httpHeaderAcceptSelected);
    }

    // to determine the Content-Type header
    const consumes: string[] = [
    ];

    return this.httpClient.get<PageMitarbeiterListRow>(`${this.basePath}/mitarbeiter`,
        {
            params: queryParameters,
            withCredentials: this.configuration.withCredentials,
            headers: headers,
            observe: observe,
            reportProgress: reportProgress
        }
    );
}

當我使用生成的服務時，它會發出這樣的請求：

但是當我使用 swagger UI 時它工作正常

為什么 swagger-ui 會發出正確的請求，但生成的 angular-client 卻沒有？

Answer 1

這是打字稿角度生成器的一個問題：

https://github.com/OpenAPITools/openapi-generator/issues/4404

已經創建了一個 Pull Request 來解決這個問題，我建議你觀看它：

https://github.com/OpenAPITools/openapi-generator/pull/4407

同時，您可以嘗試解決與 springdoc-openapi-data-rest 中可用的@PageableAsQueryParam注釋類似的問題。 也就是說，您可以在 Spring 控制器方法上使用 @Parameters 並在方法參數本身上使用@Parameter(hidden = true)以手動重新定義文檔。

這很糟糕，但它是最好的解決方案，直到拉取請求通過。

對於您編寫的方法，修復將相當簡單，只需添加@PageableAsQueryParam和@Parameter(hidden = true) ：

@PageableAsQueryParam
@SecuredMaster
@GetMapping(path = "/mitarbeiter")
@Operation(security = {@SecurityRequirement(name = "jwt")})
public Page<MitarbeiterListRow> getMitarbeiter(@Parameter(hidden = true) Pageable pageable, @RequestParam(defaultValue = "") String query) {
    return mitarbeiterRepository.findAllByUsernameContainingIgnoreCaseOrEmailContainingIgnoreCase(pageable, query, query);
}