Geração Swagger/OpenAPI para C++: visão geral de ferramentas e bibliotecas

Geração Swagger/OpenAPI para C++: visão geral de ferramentas e bibliotecas

O desenvolvimento moderno de aplicações servidoras em C++ raramente dispensa uma API REST. A especificação OpenAPI (anteriormente conhecida como Swagger) tornou-se o padrão industrial para descrever interfaces de interação entre cliente e servidor. No entanto, escrever código manualmente para processar requisições, validar dados e gerar respostas é um processo trabalhoso e propenso a erros. Felizmente, o ecossistema C++ oferece várias soluções maduras para geração automática de código a partir de especificações OpenAPI. Neste artigo, analisaremos as principais ferramentas, seus pontos fortes e daremos exemplos práticos.

1. OpenAPI Generator (openapi-generator.tech)

O gerador de código universal mais popular para dezenas de linguagens, incluindo C++. Suporta OpenAPI 3.0 e 3.1. Permite gerar tanto código de servidor (C++ REST SDK / cpprestsdk, Pistache, Restbed) quanto código de cliente.

Instalação

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

Exemplo de geração de cliente com cpprestsdk

Suponha que você tenha um arquivo petstore.yaml com a descrição da API de uma loja de animais. Após a geração, você obterá classes prontas:

#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 << "Nome do pet: " << pet->getName() << std::endl;    }).wait();    return 0;}

Prós: comunidade enorme, suporte a múltiplos frameworks, desenvolvimento ativo.

Contras: o código gerado pode ser redundante, exigindo ajustes manuais para o framework específico.

2. oat++ (oatpp.io)

Framework moderno para C++ com suporte próprio ao OpenAPI 3.0. Diferente do OpenAPI Generator, o oat++ não gera código a partir da especificação, mas permite anotar endpoints já escritos e exportar automaticamente a especificação OpenAPI.

Exemplo de anotação de endpoint

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);}

// Descrição do DTODTO(PetDto,     FIELD(Int32, id, "id"),    FIELD(String, name, "name"),    FIELD(String, status, "status"));

Após isso, o oat++ gera automaticamente o openapi.json em tempo de execução. Para geração estática, utiliza-se a ferramenta oatpp-swagger.

Prós: abordagem nativa, framework único, documentação excelente, suporte integrado ao Swagger UI.

Contras: requer o uso completo do oat++, não é adequado para projetos existentes em outros frameworks.

3. Drogon (drogon.org)

Framework web assíncrono de alto desempenho para C++17/20. Inclui o módulo drogon_ctl para geração de esqueleto de projeto e o plugin drogon::OpenApiPlugin para geração automática de documentação OpenAPI 3.0.

Exemplo de uso do OpenApiPlugin

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

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

Controlador com documentação automática:

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