Swagger Codegen 生成的 REST Assured Java 客户端 FakeApi 端点全解析

原创2026-09-24 13:04:591,928 阅读
文章标签:开发工具代码生成API设计CLI

Swagger Codegen 生成的 REST Assured Java 客户端 FakeApi 端点全解析

本文以 swagger-codegen 仓库中 REST Assured 版 Java 客户端示例生成的 API 文档 FakeApi.md 为主体,逐条讲解 Petstore 测试规范(spec)中 /fake 系列端点在 Java 客户端中的方法签名、参数约束、请求/响应媒体类型与调用方式,并结合仓库内自动生成的 FakeApi.java 源码和测试用例,说明 REST Assured 库生成客户端的操作类(Oper)设计原理。读完本文,你将能够直接使用 FakeApi 类调用全部 10 个 fake 端点,并理解如何通过 RequestSpecBuilder 定制请求、通过 execute/executeAs 获取响应。

一、FakeApi 在 Petstore 测试套件中的定位

FakeApi 是 swagger-codegen 针对 Swagger Petstore 测试规范生成的客户端 API 类之一。该规范(见 fixtures/v3/petstore3fake.yaml 等测试用规格)专门用于检验代码生成器对各种参数形态的覆盖能力,因此 FakeApi 集中了外层类型序列化、请求体 + 查询参数、PATCH 方法、表单参数多类型、枚举参数(query/header/form 三通道)、内联 additionalProperties、表单 JSON 序列化等代表性场景。

在 REST Assured 库的 Java 客户端中,所有端点均以 ApiClient.api(...) 入口创建,再通过 fake() 拿到 FakeApi 实例。生成产物位于 samples/client/petstore/java/rest-assured,其中:

所有 URI 均相对于 http://petstore.swagger.io:80/v2。

二、端点总览

下表列出了 FakeApi 的全部 10 个操作方法,对应 HTTP 方法与路径:

方法 HTTP 请求 描述
fakeOuterBooleanSerialize POST /fake/outer/boolean 外层布尔类型序列化测试
fakeOuterCompositeSerialize POST /fake/outer/composite 含外层 number 类型的对象序列化测试
fakeOuterNumberSerialize POST /fake/outer/number 外层 number 类型序列化测试
fakeOuterStringSerialize POST /fake/outer/string 外层 string 类型序列化测试
testBodyWithQueryParams PUT /fake/body-with-query-params 请求体与查询参数并存
testClientModel PATCH /fake 测试 "client" 模型
testEndpointParameters POST /fake 各种参数类型测试(假端點 / 偽のエンドポイント / 가짜 엔드 포인트)
testEnumParameters GET /fake 枚举参数测试
testInlineAdditionalProperties POST /fake/inline-additionalProperties 内联 additionalProperties 测试
testJsonFormData GET /fake/jsonFormData 表单数据的 JSON 序列化测试

从生成源码看,每个操作方法在 FakeApi 中只负责返回一个对应的操作对象(Oper),例如:

public FakeOuterBooleanSerializeOper fakeOuterBooleanSerialize() {
    return new FakeOuterBooleanSerializeOper(reqSpec);
}

真正的请求构建与执行逻辑都封装在操作对象内部,这是 REST Assured 库生成客户端的统一设计模式(下文第五节详解)。

三、公共调用骨架:ApiClient 与请求规格

原文档每个端点示例都以同一段初始化代码开头:

// Import classes:
//import io.swagger.client.ApiClient;
//import io.restassured.builder.RequestSpecBuilder;
//import io.restassured.filter.log.ErrorLoggingFilter;

FakeApi api = ApiClient.api(ApiClient.Config.apiConfig().withReqSpecSupplier(
                () -> new RequestSpecBuilder()
                        .setBaseUri("http://petstore.swagger.io:80/v2"))).fake();

需要注意:当前仓库生成的 ApiClient.java 中,Config 类提供的方法是 reqSpecSupplier(Supplier<RequestSpecBuilder>)(withReqSpecSupplier 是文档生成时的早期命名,二者作用相同),完整等价写法如下:

FakeApi api = ApiClient.api(ApiClient.Config.apiConfig()
        .reqSpecSupplier(() -> new RequestSpecBuilder()
                .setBaseUri("http://petstore.swagger.io:80/v2")))
        .fake();

其中:

  • ApiClient.Config.apiConfig() 创建空配置;
  • reqSpecSupplier 接收一个 Supplier<RequestSpecBuilder>,该 builder 会成为所有操作共享的基础请求规格(ApiClient 将其传给 FakeApi.fake(config.baseReqSpec.get()));
  • setBaseUri("http://petstore.swagger.io:80/v2") 设置基准地址;
  • .fake() 返回 FakeApi 实例。

ApiClient.Config 还支持链式返回自身(return this),便于在 reqSpecSupplier 之外继续扩展配置。

若需要更贴近真实测试的配置,可以参照 FakeApiTest.java 的做法,在 RequestSpecBuilder 上挂载 Gson 对象映射器与错误日志过滤器:

api = ApiClient.api(ApiClient.Config.apiConfig().reqSpecSupplier(
        () -> new RequestSpecBuilder()
                .setConfig(config().objectMapperConfig(objectMapperConfig().defaultObjectMapper(gson())))
                .addFilter(new ErrorLoggingFilter())
                .setBaseUri("http://petstore.swagger.io:80/v2"))).fake();

四、10 个端点逐一详解

4.1 fakeOuterBooleanSerialize:外层布尔序列化

  • HTTP:POST /fake/outer/boolean
  • 描述:Test serialization of outer boolean types
  • 参数:
名称 类型 描述 备注
body Boolean Input boolean as post body [optional]
  • 返回类型:Boolean
  • 授权:无需授权
  • 请求头:Content-Type 未定义;Accept 未定义

示例:

api.fakeOuterBooleanSerialize().execute(r -> r.prettyPeek());

对应生成源码中,该操作类的 REQ_URI = "/fake/outer/boolean",body(Boolean body) 方法通过 reqSpec.setBody(body) 写入请求体;executeAs(Function<Response, Response>) 使用 new TypeToken<Boolean>(){}.getType() 将响应反序列化为 Boolean。

4.2 fakeOuterCompositeSerialize:外层复合对象序列化

  • HTTP:POST /fake/outer/composite
  • 描述:Test serialization of object with outer number type
  • 参数:
名称 类型 描述 备注
body OuterComposite Input composite as post body [optional]
  • 返回类型:OuterComposite
  • 授权:无需授权
  • 请求头:Content-Type 未定义;Accept 未定义

示例:

api.fakeOuterCompositeSerialize().execute(r -> r.prettyPeek());

OuterComposite 模型类位于 samples/client/petstore/java/rest-assured/src/main/java/io/swagger/client/model/OuterComposite.java。

4.3 fakeOuterNumberSerialize:外层 number 序列化

  • HTTP:POST /fake/outer/number
  • 描述:Test serialization of outer number types
  • 参数:
名称 类型 描述 备注
body BigDecimal Input number as post body [optional]
  • 返回类型:BigDecimal
  • 授权:无需授权
  • 请求头:Content-Type 未定义;Accept 未定义

示例:

api.fakeOuterNumberSerialize().execute(r -> r.prettyPeek());

4.4 fakeOuterStringSerialize:外层 string 序列化

  • HTTP:POST /fake/outer/string
  • 描述:Test serialization of outer string types
  • 参数:
名称 类型 描述 备注
body String Input string as post body [optional]
  • 返回类型:String
  • 授权:无需授权
  • 请求头:Content-Type 未定义;Accept 未定义

示例:

api.fakeOuterStringSerialize().execute(r -> r.prettyPeek());

4.5 testBodyWithQueryParams:请求体 + 查询参数

  • HTTP:PUT /fake/body-with-query-params
  • 参数:
名称 类型 描述 备注
body User 必填
query String 必填
  • 返回类型:null(空响应体)
  • 授权:无需授权
  • 请求头:Content-Type application/json;Accept 未定义

示例:

api.testBodyWithQueryParams()
    .body(body)
    .queryQuery(query).execute(r -> r.prettyPeek());

从源码看,body(User body) 调用 reqSpec.setBody(body),而 queryQuery(Object... query) 调用 reqSpec.addQueryParam("query", query)——查询参数方法接受可变参数,这是 REST Assured 库生成代码的统一风格(见 FakeApi.java)。

4.6 testClientModel:测试 "client" 模型

  • HTTP:PATCH /fake
  • 描述:To test "client" model
  • 参数:
名称 类型 描述 备注
body Client client model 必填
  • 返回类型:Client
  • 授权:无需授权
  • 请求头:Content-Type application/json;Accept application/json

示例:

api.testClientModel()
    .body(body).execute(r -> r.prettyPeek());

该端点对应源码中的 TestClientModelOper,REQ_URI = "/fake",执行时使用 PATCH 方法(when().request(PATCH, REQ_URI)),返回类型反序列化为 Client 模型。Client 模型类位于 samples/client/petstore/java/rest-assured/src/main/java/io/swagger/client/model/Client.java。

4.7 testEndpointParameters:多类型表单参数压测

  • HTTP:POST /fake
  • 描述:Fake endpoint for testing various parameters 假端點 偽のエンドポイント 가짜 엔드 포인트
  • 参数(全部为表单参数,方法名统一带 Form 后缀):
名称 类型 描述 备注
number BigDecimal None 必填
_double Double None 必填
patternWithoutDelimiter String None 必填
_byte byte[] None 必填
integer Integer None [optional]
int32 Integer None [optional]
int64 Long None [optional]
_float Float None [optional]
string String None [optional]
binary byte[] None [optional]
date LocalDate None [optional]
dateTime OffsetDateTime None [optional]
password String None [optional]
paramCallback String None [optional]
  • 返回类型:null(空响应体)
  • 授权:http_basic_test(HTTP Basic 认证)
  • 请求头:Content-Type application/xml; charset=utf-8, application/json; charset=utf-8;Accept 同左

示例:

api.testEndpointParameters()
    .numberForm(number)
    ._doubleForm(_double)
    .patternWithoutDelimiterForm(patternWithoutDelimiter)
    ._byteForm(_byte).execute(r -> r.prettyPeek());

该端点是唯一需要 HTTP Basic 认证的 fake 端点,也是参数类型最全的端点。注意生成代码中的两个细节(见 FakeApi.java):

  • Java 关键字冲突处理:double、float、byte、callback 等保留字/常见名被转义为 _double、_float、_byte、paramCallback,方法名使用 _doubleForm、_floatForm、_byteForm、paramCallbackForm;
  • 表单键名与 OpenAPI 参数名保持一致(如 pattern_without_delimiter、callback),所有表单方法均通过 reqSpec.addFormParam(name, values) 写入;
  • 日期类型 date 映射为 LocalDate、dateTime 映射为 OffsetDateTime,依赖 threetenbp 库。

4.8 testEnumParameters:三通道枚举参数

  • HTTP:GET /fake
  • 描述:To test enum parameters
  • 参数:
名称 类型 描述 备注
enumFormStringArray List<String> Form parameter enum test (string array) [optional] [enum: >, $]
enumFormString String Form parameter enum test (string) [optional] [default to -efg] [enum: _abc, -efg, (xyz)]
enumHeaderStringArray List<String> Header parameter enum test (string array) [optional] [enum: >, $]
enumHeaderString String Header parameter enum test (string) [optional] [default to -efg] [enum: _abc, -efg, (xyz)]
enumQueryStringArray List<String> Query parameter enum test (string array) [optional] [enum: >, $]
enumQueryString String Query parameter enum test (string) [optional] [default to -efg] [enum: _abc, -efg, (xyz)]
enumQueryInteger Integer Query parameter enum test (double) [optional] [enum: 1, -2]
enumQueryDouble Double Query parameter enum test (double) [optional] [enum: 1.1, -1.2]
  • 返回类型:null(空响应体)
  • 授权:无需授权
  • 请求头:Content-Type */*;Accept */*

示例:

api.testEnumParameters().execute(r -> r.prettyPeek());

该端点覆盖枚举参数在表单、请求头、查询三个通道的传输。生成源码(FakeApi.java)按通道为方法命名:xxxForm 走 addFormParam、xxxQuery 走 addQueryParam、xxxHeader 走 reqSpec.addHeader(...)。注意字符串数组枚举(enumFormStringArray 等)的合法值仅 > 与 $ 两个符号,非常适合验证特殊字符在 URL/表单编码中的处理。

4.9 testInlineAdditionalProperties:内联 additionalProperties

  • HTTP:POST /fake/inline-additionalProperties
  • 描述:test inline additionalProperties
  • 参数:
名称 类型 描述 备注
param Object request body 必填
  • 返回类型:null(空响应体)
  • 授权:无需授权
  • 请求头:Content-Type application/json;Accept 未定义

示例:

api.testInlineAdditionalProperties()
    .body(param).execute(r -> r.prettyPeek());

该端点用于验证规范中内联 additionalProperties 的请求体传递,body(Object param) 直接调用 reqSpec.setBody(param)(FakeApi.java),体现了 REST Assured 对任意对象请求体的通用支持。

4.10 testJsonFormData:表单数据的 JSON 序列化

  • HTTP:GET /fake/jsonFormData
  • 描述:test json serialization of form data
  • 参数:
名称 类型 描述 备注
param String field1 必填
param2 String field2 必填
  • 返回类型:null(空响应体)
  • 授权:无需授权
  • 请求头:Content-Type application/json;Accept 未定义

示例:

api.testJsonFormData()
    .paramForm(param)
    .param2Form(param2).execute(r -> r.prettyPeek());

生成代码中 paramForm(Object... param) 与 param2Form(Object... param2) 分别调用 reqSpec.addFormParam("param", param) 和 reqSpec.addFormParam("param2", param2)(FakeApi.java),用于测试表单字段经 JSON 序列化后的传输行为。

五、源码级原理:操作对象(Oper)与执行模型

从仓库生成的 FakeApi.java 可以清晰归纳 REST Assured 库生成客户端的三层执行模型,这也是理解本文所有端点的关键:

1. 操作对象持有两份规格 每个操作类(如 FakeOuterBooleanSerializeOper)都持有 RequestSpecBuilder reqSpec 与 ResponseSpecBuilder respSpec。无参构造和带参构造都会立即设置该端点默认的 Content-Type 与 Accept:

reqSpec.setContentType("application/json");
reqSpec.setAccept("application/json");
this.respSpec = new ResponseSpecBuilder();

2. 请求参数方法即写即用 参数设置方法(body、xxxForm、xxxQuery、xxxHeader)直接修改 reqSpec,返回 this 以支持链式调用。REST Assured 的 builder 语义在此被完整保留。

3. 执行方法统一签名 所有操作类的执行入口都是:

public <T> T execute(Function<Response, T> handler) {
    return handler.apply(RestAssured.given().spec(reqSpec.build())
            .expect().spec(respSpec.build())
            .when().request(POST, REQ_URI));
}

execute 接收一个 Function<Response, T> 响应处理器(文档示例中的 r -> r.prettyPeek() 即打印响应体);有返回值的端点额外提供 executeAs(Function<Response, Response>),借助 Gson 的 TypeToken 将响应体反序列化为目标类型。

此外,每个操作类还暴露两个定制入口:

  • reqSpec(Consumer<RequestSpecBuilder> consumer):对请求规格做二次定制;
  • respSpec(Consumer<ResponseSpecBuilder> consumer):对响应断言规格做二次定制。

配合 ResponseSpecBuilders.java 提供的工具方法,可以方便地断言响应状态码:

import static io.swagger.client.ResponseSpecBuilders.*;

api.testClientModel()
    .body(client)
    .execute(validatedWith(shouldBeCode(200)));

其中 shouldBeCode(int code) 构造 expectStatusCode(code) 的 ResponseSpecBuilder,validatedWith(...) 将其包装为响应处理函数——这是生成客户端中"请求构建、响应校验、业务处理"三者解耦的核心手法。

六、REST Assured 库的依赖与构建

rest-assured 是 swagger-codegen Java 生成器(JavaClientCodegen.java)提供的可选 library 之一,其 Maven 依赖模板位于 modules/swagger-codegen/src/main/resources/Java/libraries/rest-assured/pom.mustache。生成后的项目核心依赖包括:

依赖 版本(模板默认值) 用途
io.rest-assured:rest-assured 3.1.0 REST 断言与请求 DSL
com.google.code.gson:gson 2.6.1 JSON 序列化
io.gsonfire:gson-fire 1.8.2 Gson 扩展(枚举等类型适配)
com.squareup.okio:okio 1.13.0 IO 底层支持
org.threeten:threetenbp 1.4.1 LocalDate / OffsetDateTime 支持(可选,由 threetenbp 开关控制)
junit:junit 4.13.1 测试作用域

模板同时内置 maven-compiler-plugin(Java 1.8)与 surefire 配置。若要复现这份示例工程,可通过 Java 生成器指定 --library rest-assured 对 Petstore 规格重新生成,或直接查看/运行仓库内已生成的 samples/client/petstore/java/rest-assured 样例(其 src/main/java 即本文所有示例的实际编译产物)。

七、结语

FakeApi 虽名为 "fake",实为 swagger-codegen 对 REST Assured Java 客户端能力的系统性自测:外层类型序列化、请求体 + 查询参数混用、PATCH 方法、保留字参数转义、三通道枚举、内联附加属性与表单 JSON 序列化一应俱全。结合 FakeApi.md 的 API 文档、FakeApi.java 的实现源码与 FakeApiTest.java 的测试骨架,开发者既能快速上手调用,也能从模板与生成产物中提炼出属于自己的客户端代码生成模式。

登录后查看全文
swagger-codegen