Swagger Codegen 生成的 REST Assured Java 客户端 FakeApi 端点全解析
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,其中:
- FakeApi.java:本篇文章核心 API 类;
- ApiClient.java:客户端入口与公共配置;
- FakeApiTest.java:配套的 JUnit 测试骨架。
所有 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;Acceptapplication/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 的测试骨架,开发者既能快速上手调用,也能从模板与生成产物中提炼出属于自己的客户端代码生成模式。