Servidor OpenAPI para Delphi

Visão geral

TsgcOpenAPIServer

Um único componente Delphi que transforma uma especificação OpenAPI em um servidor HTTP/2 em execução, validado e autodocumentado.

Classe do componente

TsgcOpenAPIServer

Transporte

HTTP/1.1, HTTP/2, upgrade para WebSocket, TLS via OpenSSL ou SChannel

Formatos de spec

OpenAPI 3.0, OpenAPI 3.1, Swagger 2.0 (convertido automaticamente)

Plataformas

Windows, Linux, macOS — Delphi 7 a 13, C++Builder, FPC

Edição

Standard / Professional / Enterprise — todas incluem o servidor

Construído sobre

Servidor HTTP do sgcWebSockets (mesmo pipeline de TLS, HTTP/2, autenticação e logging)

Duas formas de construir

Spec-first ou Code-first — Você Escolhe

O mesmo componente roda em ambos os modos. Comece a partir de um contrato YAML/JSON, ou descreva a API em Delphi e deixe o componente publicar a especificação para você.

1. Spec-first

Carregue openapi.yaml, vincule handlers aos operation IDs e comece a servir. Rotas, binding de parâmetros, content negotiation e validação vêm direto do contrato — você só escreve a lógica de negócio.

Ideal para: equipes com um contrato de design compartilhado, integração API-led ou back-ends poliglotas em que a spec é a fonte da verdade.

2. Code-first

Registre handlers em Pascal com anotações (path, verbo, schema da requisição, schema da resposta, segurança). O componente constrói o documento OpenAPI em tempo de execução e o expõe em /openapi.json.

Ideal para: prototipagem rápida, serviços internos ou portar uma superfície REST existente de TIdHTTPServer / DataSnap para uma API autodocumentada.

Início Rápido

Um Servidor Funcional em 20 Linhas

Solte o componente em um formulário, aponte-o para um documento OpenAPI, vincule uma operação, aperte Run. Essa é toda a configuração.

Delphi

uses
  sgcOpenAPI_Server, sgcOpenAPI_Types, sgcHTTP_Server;

procedure TForm1.FormCreate(Sender: TObject);
begin
  FServer := TsgcOpenAPIServer.Create(nil);
  FServer.HTTPServer := sgcHTTPServer1;        // reuse the sgcWebSockets HTTP/2 server
  FServer.Spec.LoadFromFile('petstore.yaml');  // any OpenAPI 3.x doc
  FServer.PublishSpecPath := '/openapi.json';
  FServer.SwaggerUIPath   := '/docs';
  FServer.RedocPath       := '/redoc';

  // Bind one operation defined in the spec (operationId = "getPetById")
  FServer.OnOperation_getPetById :=
    procedure(const Ctx: TsgcOpenAPIContext)
    var
      oPet: TJSONObject;
    begin
      oPet := TJSONObject.Create;
      oPet.AddPair('id',     Ctx.PathParams['petId']);
      oPet.AddPair('name',   'Rex');
      oPet.AddPair('status', 'available');
      Ctx.RespondJSON(200, oPet);
    end;

  sgcHTTPServer1.Port   := 8080;
  sgcHTTPServer1.Active := True;
end;

O que você ganha de cara: GET /pets/{petId} serve o handler acima, GET /openapi.json devolve a spec ao vivo, GET /docs abre o Swagger UI, GET /redoc abre o Redoc — com HTTP/2 e TLS já ativos se sgcHTTPServer1 estiver configurado.

Roteamento

Os parâmetros declarados no documento OpenAPI são parseados, validados por tipo e expostos através de um único contexto tipado. Tipos errados devolvem 400 Bad Request antes mesmo do seu handler rodar.

Delphi

// spec snippet
//   /pets:
//     get:
//       operationId: listPets
//       parameters:
//         - name: limit       in: query    schema: { type: integer, maximum: 100 }
//         - name: status      in: query    schema: { type: string, enum: [available, pending, sold] }
//         - name: X-Tenant-Id in: header   required: true

FServer.OnOperation_listPets :=
  procedure(const Ctx: TsgcOpenAPIContext)
  var
    vLimit:  Integer;
    vStatus: string;
    vTenant: string;
  begin
    vLimit  := Ctx.QueryParamInt('limit', 20);     // default 20
    vStatus := Ctx.QueryParam   ('status', 'available');
    vTenant := Ctx.HeaderParam  ('X-Tenant-Id');   // required → validated

    Ctx.RespondJSON(200, PetRepo.List(vTenant, vStatus, vLimit));
  end;

Validação

Validação de Schema nas duas direções

Cada body que chega é validado contra o schema requestBody da operação. Cada resposta é validada contra o código de status declarado. Divergências devolvem problem-details RFC 7807 com diagnóstico no nível do campo.

Validação de requisições

Campos obrigatórios, coerção de tipos, pertinência a enum, validadores de format (email, uuid, date-time, ipv4/6), minLength / maxLength, minimum / maximum, pattern, additionalProperties, oneOf / anyOf / allOf — tudo aplicado antes do seu handler rodar.

Validação de respostas

Opcional em produção, rigorosa em desenvolvimento. Ajuda você a pegar o dia em que seu handler devolve um campo extra que não está no contrato antes que um consumidor a jusante quebre.

Validadores personalizados

Plugue no OnBeforeValidate para adicionar regras de domínio (código de moeda suportado, SKU existe, tenant está ativo). Devolve o mesmo envelope RFC 7807 dos validadores embutidos para uma UX de erro uniforme.

JSON — exemplo de resposta 400

{
  "type":   "https://example.com/probs/validation",
  "title":  "Request body failed schema validation",
  "status": 400,
  "errors": [
    { "path": "/email",    "message": "not a valid email address" },
    { "path": "/age",      "message": "value 213 exceeds maximum 120" },
    { "path": "/status",   "message": "value 'archived' not in enum [active,pending]" }
  ]
}

Segurança

Esquemas de Auth Conectados Direto da Spec

Cada securityScheme declarado no documento é aplicado automaticamente. Você só escreve o lookup de credenciais — o componente cuida do parsing, dos headers de challenge e das respostas 401/403.

API Key

Header, query ou cookie. Várias chaves por operação. Comparação em tempo constante.

HTTP Basic / Bearer

RFC 7617 / RFC 6750 com suporte a realm. Credenciais nunca vão para o log.

JWT (RS256 / ES256 / HS256)

Auto-fetch e cache de JWKS. Checagens de issuer, audience, expiração e claims customizados.

OAuth2

Fluxos Authorization Code, Client Credentials, Password e Implicit. PKCE suportado.

OpenID Connect

Documento de discovery carregado de /.well-known/openid-configuration. ID token validado contra o JWKS.

mTLS

Exigência de certificado de cliente por operação. Common Name e SAN disponíveis no contexto.

Delphi — hook de validação de JWT

FServer.Security.JWT.JWKSUri := 'https://auth.example.com/.well-known/jwks.json';
FServer.Security.JWT.Audience := 'api.example.com';
FServer.Security.JWT.Issuer   := 'https://auth.example.com/';

FServer.OnAuthorize :=
  procedure(const Ctx: TsgcOpenAPIContext; var Allow: Boolean)
  begin
    // Token already verified. Apply business rule on a custom claim.
    Allow := Ctx.JWT.Claims['tenant'] = Ctx.PathParams['tenant'];
  end;

Autodocumentado

Swagger UI e Redoc Embutidos

Sem dependências externas, sem Node.js, sem swagger-codegen no pipeline de deploy. As duas UIs vêm empacotadas dentro do componente e servem direto da spec em tempo de execução.

/openapi.json e /openapi.yaml

O documento ao vivo — sempre em sincronia com o que o servidor realmente entrega. Aponte qualquer gerador de cliente (sgcOpenAPI, openapi-generator, oapi-codegen) para essa URL.

/docs — Swagger UI

O Swagger UI interativo já conhecido — experimente operações, navegue por schemas, veja exemplos. Tema, deepLinking e redirect de OAuth2 configuráveis.

/redoc — Redoc

O layout limpo de três painéis do Redoc para documentação de API com cara de estática. Mesma fonte, apresentação diferente.

Formatos wire

Content Negotiation Bem Feita

application/json

UTF-8, estrito RFC 8259. Números, booleanos, nulls, objetos aninhados e arrays.

application/yaml

YAML 1.2 com parsing ciente do schema. Útil para bodies editados à mão.

application/x-www-form-urlencoded

Posts de formulário clássicos — vinculados ao schema da requisição como qualquer outro body.

multipart/form-data

Uploads de arquivos com limites de tamanho, allow lists de MIME-types e binding de schema por parte.

text/event-stream (SSE)

Respostas em stream de longa duração — reaproveita o writer SSE do sgcWebSockets.

application/octet-stream

Download/upload binário cru com suporte a byte-range request.

Integração

Um Servidor HTTP, Várias Superfícies

O TsgcOpenAPIServer conecta-se ao mesmo servidor HTTP/2 do sgcWebSockets que hospeda seus endpoints WebSocket, streams de IA/LLM e arquivos estáticos. Uma porta, um certificado TLS, um stream de logs.

Multiplexação HTTP/2

Centenas de operações REST e uma assinatura WebSocket de longa duração compartilham a mesma conexão TLS. Clientes de navegador ganham um handshake em uma só ida e volta, você fica com menos sockets para manter vivos.

Promoção para WebSocket

Declare x-sgc-upgrade: websocket em um path e o componente faz o upgrade RFC 6455 para você — a mesma operação atende REST e streaming bidirecional.

Rotas de assets estáticos

Coloque o build da SPA em /app no mesmo componente — URLs limpas, gzip, brotli, ETag e server-push HTTP/2 de graça.

Onde ele brilha

Deployments Típicos

APIs REST públicas

Versionadas, testadas por contrato, com SDKs auto-gerados que seus clientes podem baixar de /openapi.json.

Microsserviços internos

Contratos serviço-a-serviço que sobrevivem a refactors — a spec é o teste de integração.

Gateways industriais / IoT

Dispositivos de edge expondo um plano de controle REST documentado mais uma superfície de telemetria MQTT ou WebSocket a partir do mesmo binário Delphi.

Receptores de webhook

O payload do webhook de cada provedor vira um record Pascal tipado — Stripe, GitHub, Twilio, Slack — com validação e idempotência embutidas.

Modernização de legado

Envolva um back-end antigo de DataSnap ou RemObjects atrás de uma superfície OpenAPI limpa sem reescrever a lógica de negócio.

BFF (Backend-for-Frontend)

Agregue duas ou três APIs upstream atrás de uma única spec com formato do consumidor — sua SPA ou app mobile fala com um único endpoint tipado.

Melhor juntos