@@ -70,17 +70,17 @@ HICAL_SCHEMA_NAME(ErrorResponse, "ErrorResponse")
7070
7171**类型映射规则**（由 `jsonSchema<T>()` 在编译期推导）：
7272
73- | C++ 类型 | OpenAPI Schema |
74- |---| ---|
75- | `std::string` | `{"type":"string"}` |
76- | `bool` | `{"type":"boolean"}` |
77- | `int` / `int32_t` | `{"type":"integer","format":"int32"}` |
78- | `int64_t` | `{"type":"integer","format":"int64"}` |
79- | `float` | `{"type":"number","format":"float"}` |
80- | `double` | `{"type":"number","format":"double"}` |
81- | `std::vector<T>` | `{"type":"array","items":{...}}` |
73+ | C++ 类型 | OpenAPI Schema |
74+ | -------------------------------------------------- | ------------------------------------- |
75+ | `std::string` | `{"type":"string"}` |
76+ | `bool` | `{"type":"boolean"}` |
77+ | `int` / `int32_t` | `{"type":"integer","format":"int32"}` |
78+ | `int64_t` | `{"type":"integer","format":"int64"}` |
79+ | `float` | `{"type":"number","format":"float"}` |
80+ | `double` | `{"type":"number","format":"double"}` |
81+ | `std::vector<T>` | `{"type":"array","items":{...}}` |
8282| 嵌套 `HICAL_JSON` 结构体（有 `HICAL_SCHEMA_NAME`） | `{"$ref":"#/components/schemas/XXX"}` |
83- | 嵌套 `HICAL_JSON` 结构体（无名称） | 内联展开完整 schema |
83+ | 嵌套 `HICAL_JSON` 结构体（无名称） | 内联展开完整 schema |
8484
8585`REQUIRED(field)` 会把该字段加入 schema 的 `required` 数组，与业务验证逻辑保持一致。
8686
@@ -149,15 +149,15 @@ struct UserHandler
149149
150150** builder 函数速查** ：
151151
152- | 函数 | 作用 |
153- | ---| ---|
154- | ` builder::summary(info, "...") ` | 端点一句话摘要 |
155- | ` builder::description(info, "...") ` | 详细描述（支持 Markdown） |
156- | ` builder::tags(info, {"tag1", "tag2"}) ` | 分组标签，Swagger UI 按此折叠 |
157- | ` builder::request<T>(info, "描述", required) ` | 请求体 DTO，自动引用 schema |
158- | ` builder::response<T>(info, 状态码, "描述") ` | 有 body 的响应 |
159- | ` builder::responseDesc(info, 状态码, "描述") ` | 无 body 的响应（204/404 等） |
160- | ` builder::pathParam(info, "name", "type", "描述") ` | 路径参数说明 |
152+ | 函数 | 作用 |
153+ | -------------------------------------------------- | ----------------------------- |
154+ | ` builder::summary(info, "...") ` | 端点一句话摘要 |
155+ | ` builder::description(info, "...") ` | 详细描述（支持 Markdown） |
156+ | ` builder::tags(info, {"tag1", "tag2"}) ` | 分组标签，Swagger UI 按此折叠 |
157+ | ` builder::request<T>(info, "描述", required) ` | 请求体 DTO，自动引用 schema |
158+ | ` builder::response<T>(info, 状态码, "描述") ` | 有 body 的响应 |
159+ | ` builder::responseDesc(info, 状态码, "描述") ` | 无 body 的响应（204/404 等） |
160+ | ` builder::pathParam(info, "name", "type", "描述") ` | 路径参数说明 |
161161
162162---
163163
@@ -336,14 +336,14 @@ HICAL_API(getUserOrders,
336336
337337Oat++ 是 C++ 生态里另一个有 Swagger 集成的框架，来看看标注风格的差异：
338338
339- | 维度 | Hical | Oat++ |
340- |---| ---| ---|
341- | 路由标注 | `HICAL_HANDLER` + `HICAL_API` | `ENDPOINT_INFO` + `ENDPOINT` |
342- | Schema 生成 | 从 `HICAL_JSON` 自动推导 | 需要继承 `oatpp::DTO` 并用 `DTO_FIELD` |
343- | 响应声明 | `builder::response<T>(info, 200, "...")` | `info->addResponse<Object<T>>(Status::CODE_200)` |
344- | 新依赖 | 零（复用 Boost.JSON） | 引入 oatpp-swagger 库 |
345- | 编译期类型检查 | `static_assert` + concepts | 运行时反射 |
346- | 内存模型 | 零堆分配查找（透明哈希） | 智能指针 DTO 对象 |
339+ | 维度 | Hical | Oat++ |
340+ | -------------- | ---------------------------------------- | ------------------------------------------------ |
341+ | 路由标注 | `HICAL_HANDLER` + `HICAL_API` | `ENDPOINT_INFO` + `ENDPOINT` |
342+ | Schema 生成 | 从 `HICAL_JSON` 自动推导 | 需要继承 `oatpp::DTO` 并用 `DTO_FIELD` |
343+ | 响应声明 | `builder::response<T>(info, 200, "...")` | `info->addResponse<Object<T>>(Status::CODE_200)` |
344+ | 新依赖 | 零（复用 Boost.JSON） | 引入 oatpp-swagger 库 |
345+ | 编译期类型检查 | `static_assert` + concepts | 运行时反射 |
346+ | 内存模型 | 零堆分配查找（透明哈希） | 智能指针 DTO 对象 |
347347
348348Hical 的核心差异在于 schema 是**编译期从类型信息推导**的，而不是运行时通过 DTO 对象的虚函数反射。这意味着写错类型在编译阶段就能发现，而不是部署后才看到错误的文档。
349349
0 commit comments