Swagger

告别手写 API 文档：Hical OpenAPI 自动生成 + Swagger UI 一键集成 你是否经历过这种情况：花了半天写好 Swagger 注解，一个需求变更，参数名改了，文档却忘了同步——测试组拿着旧文档联调，来回扯皮两小时？ API 文档和代码永远对不上，是后端开发者的经典痛点。本文介绍如何用 Hical 框架的 OpenAPI 模块，让文档从代码中自动生成，彻底消灭这个问题。 一、背景：OpenAPI 3.0 是什么 OpenAPI 3.0（即过去的 Swagger 规范）是描述 HTTP API 的行业标准 JSON/YAML 格式。有了它： Swagger UI / Redoc 可以直接渲染成可交互的文档页面 前端可以一键生成 TypeScript 类型定义 QA 可以直接在浏览器里填参数发请求 手写 OpenAPI YAML 很繁琐，维护成本高。Hical 的方案是：从 C++ 类型系统直接推导出 schema，标注一次，文档自动生成。 二、三步集成概览 1 2 3 步骤 1 定义 DTO，加 HICAL_JSON + HICAL_SCHEMA_NAME 步骤 2 标注路由，加 HICAL_API + builder::* 步骤 3 main() 中 registerRoutesWithOpenApi + serveOpenApi 不需要任何新依赖，OpenAPI 模块默认随 Hical 一起编译（HICAL_WITH_OPENAPI=ON 是默认值），底层复用已有的 Boost.JSON。 ...

设计 Hical OpenAPI 模块的心得 一、为什么要做这件事 Hical 框架从一开始就内建了两套反射基础设施：MetaJson（DTO 字段反射）和 MetaRoutes（路由反射）。这意味着框架在编译期就已经知道"每个结构体有哪些字段、叫什么名字、什么类型、是否必填"以及"每个 Handler 有哪些路由、什么方法、什么路径"。 这些信息恰好是生成 OpenAPI spec 所需要的全部输入。 在 C++ Web 框架领域，Drogon 通过插件支持 Swagger，Oat++ 有内建的 API 文档生成，但没有任何 C++ 框架能做到"从 C++20 宏反射层自动导出 OpenAPI 3.0 spec"这件事。这是 Hical 反射层设计的一个天然延伸，也是最有潜力的差异化卖点。 做之前我最担心的问题是：C++20 的宏回退路径能不能提取足够的类型信息来生成 JSON Schema？C++26 的 jsonSchema<T>() 可以用 std::meta::type_of(member) 直接获取字段类型，但 C++20 只有 FieldDescriptor<Class, FieldType> 的成员指针。后来发现，通过 decltype(std::declval<T>().*(field.pointer)) 在 fold expression 的每次展开中推导出具体的 FieldType，完全可以做到。这个验证结果让我决定动手。 二、架构决策 四层分离 最终的架构是四层设计： 1 2 3 4 Layer 4: OpenApiEndpoint.h — serveOpenApi() / Swagger UI Layer 3: OpenApiDocument.h/cpp — 文档组装 Layer 2: OpenApiRegistry.h/cpp — 路由元数据收集 + 标注宏 Layer 1: OpenApiSchema.h — JSON Schema 生成 这不是一开始就想好的。最初的想法是把所有东西塞进一个 OpenApi.h 里——Schema 生成、路由收集、文档组装、端点注册全放一起。但很快发现几个问题： ...