Swagger/OpenAPI 生成用于 C++：工具与库概览

Swagger/OpenAPI 生成用于 C++：工具与库概览

现代 C++ 服务器端应用程序开发很少能离开 REST API。OpenAPI 规范（以前称为 Swagger）已成为描述客户端与服务器之间交互接口的行业标准。然而，手动编写用于处理请求、验证数据和生成响应的代码是一个耗时且容易出错的过程。幸运的是，C++ 生态系统提供了几种成熟的解决方案，用于根据 OpenAPI 规范自动生成代码。在本文中，我们将分析主要工具、它们的优势，并提供实际示例。

1. OpenAPI Generator (openapi-generator.tech)

最流行的通用代码生成器，支持数十种语言，包括 C++。支持 OpenAPI 3.0 和 3.1。允许生成服务器端代码（C++ REST SDK / cpprestsdk、Pistache、Restbed）和客户端代码。

安装

npm install @openapitools/openapi-generator-cli -g# 或通过 Docker：docker run --rm -v ${PWD}:/local openapitools/openapi-generator-cli generate \  -i /local/petstore.yaml \  -g cpp-restsdk \  -o /local/out/cpp-client

使用 cpprestsdk 生成客户端的示例

假设您有一个描述宠物商店 API 的文件 petstore.yaml。生成后，您将获得现成的类：

#include "ApiClient.h"#include "PetApi.h"

int main() {    auto client = std::make_shared<ApiClient>();    PetApi api(client);

    api.getPetById(1).then([](std::shared_ptr<Pet> pet) {        std::cout << "Pet name: " << pet->getName() << std::endl;    }).wait();    return 0;}

优点：庞大的社区，支持众多框架，积极开发。

缺点：生成的代码可能过于冗余，需要针对特定框架进行手动调整。

2. oat++ (oatpp.io)

一个现代化的 C++ 框架，原生支持 OpenAPI 3.0。与 OpenAPI Generator 不同，oat++ 不会从规范生成代码，而是允许您注解已编写的端点，并自动导出 OpenAPI 规范。

端点注解示例

ENDPOINT("GET", "/pets/{petId}", getPetById) {    auto dto = PetDto::createShared();    dto->id = request->getPathVariable("petId");    dto->name = "Rex";    dto->status = "available";    return createDtoResponse(Status::CODE_200, dto);}

// DTO 描述DTO(PetDto,     FIELD(Int32, id, "id"),    FIELD(String, name, "name"),    FIELD(String, status, "status"));

之后，oat++ 会在运行时自动生成 openapi.json。对于静态生成，可以使用 oatpp-swagger 工具。

优点：原生方法，统一的框架，优秀的文档，内置 Swagger UI 支持。

缺点：需要完整使用 oat++，不适用于基于其他框架的现有项目。

3. Drogon (drogon.org)

一个高性能的异步 Web 框架，适用于 C++17/20。包含用于生成项目骨架的 drogon_ctl 模块，以及用于自动生成 OpenAPI 3.0 文档的 drogon::OpenApiPlugin 插件。

使用 OpenApiPlugin 的示例

#include <drogon/drogon.h>using namespace drogon;

int main() {    app().registerController(std::make_shared<PetController>());    app().addPlugin("drogon::OpenApiPlugin", {        {"title", "Pet Store API"},        {"version", "1.0.0"}    });    app().run();}

带有自动文档的控制器：

class PetController : public HttpController<PetController> {public:    MET