Servidor OpenAPI para Delphi

De un vistazo

TsgcOpenAPIServer

Un único componente Delphi que convierte una especificación OpenAPI en un servidor HTTP/2 en ejecución, validado y autodocumentado.

Clase de componente

TsgcOpenAPIServer

Transporte

HTTP/1.1, HTTP/2, upgrade a WebSocket, TLS vía OpenSSL o SChannel

Formatos de spec

OpenAPI 3.0, OpenAPI 3.1, Swagger 2.0 (conversión automática)

Plataformas

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

Edición

Standard / Professional / Enterprise — todas incluyen el servidor

Construido sobre

Servidor HTTP de sgcWebSockets (mismo pipeline de TLS, HTTP/2, autenticación y logging)

Dos formas de construir

Spec-first o Code-first — Tú Eliges

El mismo componente funciona en ambos modos. Empieza desde un contrato YAML/JSON, o describe la API en Delphi y deja que el componente publique la especificación por ti.

1. Spec-first

Carga openapi.yaml, vincula handlers a los operation IDs y empieza a servir. Las rutas, el binding de parámetros, la negociación de contenido y la validación vienen directamente del contrato — solo escribes la lógica de negocio.

Ideal para: equipos con un contrato de diseño compartido, integración guiada por la API o backends políglotas donde la spec es la fuente de verdad.

2. Code-first

Registra los handlers en Pascal con anotaciones (path, verbo, esquema de solicitud, esquema de respuesta, seguridad). El componente construye el documento OpenAPI en tiempo de ejecución y lo expone en /openapi.json.

Ideal para: prototipado rápido, servicios internos o migrar una superficie REST de TIdHTTPServer / DataSnap existente a una API autodocumentada.

Guía Rápida

Un Servidor Funcional en 20 Líneas

Coloca el componente en un formulario, apúntalo a un documento OpenAPI, vincula una operación y pulsa Run. Esa es toda la configuración.

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;

Lo que obtienes desde el primer momento: GET /pets/{petId} sirve el handler de arriba, GET /openapi.json devuelve la spec en vivo, GET /docs abre Swagger UI, GET /redoc abre Redoc — con HTTP/2 y TLS ya activos si sgcHTTPServer1 los tiene configurados.

Enrutado

Los parámetros declarados en el documento OpenAPI se parsean, se verifican por tipo y se exponen a través de un único contexto tipado. Los tipos incorrectos devuelven 400 Bad Request antes de que se ejecute tu handler.

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;

Validación

Validación de Esquemas en Ambas Direcciones

Cada cuerpo entrante se valida contra el esquema de requestBody de la operación. Cada respuesta se valida contra el código de estado declarado. Los desajustes devuelven problem-details según RFC 7807 con diagnósticos a nivel de campo.

Validación de solicitudes

Campos obligatorios, coerción de tipos, pertenencia a enums, validadores de format (email, uuid, date-time, ipv4/6), minLength / maxLength, minimum / maximum, pattern, additionalProperties, oneOf / anyOf / allOf — todo aplicado antes de que se ejecute tu handler.

Validación de respuestas

Opcional en producción, estricta en desarrollo. Te ayuda a detectar el día en que tu handler devuelve un campo extra que no está en el contrato antes de que un consumidor downstream se rompa.

Validadores personalizados

Engánchate a OnBeforeValidate para añadir reglas de dominio (el código de moneda está soportado, el SKU existe, el tenant está activo). Devuelve el mismo sobre RFC 7807 que los validadores integrados para una UX de error uniforme.

JSON — ejemplo de respuesta 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]" }
  ]
}

Seguridad

Esquemas de Auth Cableados Desde la Spec

Cada securityScheme declarado en el documento se aplica automáticamente. Tú solo escribes la búsqueda de credenciales — el componente se encarga del parsing, las cabeceras de challenge y las respuestas 401/403.

API Key

Header, query o cookie. Múltiples claves por operación. Comparación en tiempo constante.

HTTP Basic / Bearer

RFC 7617 / RFC 6750 con soporte de realm. Las credenciales nunca se registran en logs.

JWT (RS256 / ES256 / HS256)

Auto-fetch y caché de JWKS. Comprobaciones de issuer, audience, expiración y claims personalizados.

OAuth2

Flujos Authorization Code, Client Credentials, Password e Implicit. PKCE soportado.

OpenID Connect

Documento de discovery cargado desde /.well-known/openid-configuration. ID token validado contra JWKS.

mTLS

Aplicación de certificado de cliente por operación. Common Name y SAN disponibles en el contexto.

Delphi — hook de validación 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 y Redoc Embebidos

Sin dependencias externas, sin Node.js, sin swagger-codegen en el pipeline de despliegue. Ambas interfaces están integradas dentro del componente y se sirven directamente desde la spec en tiempo de ejecución.

/openapi.json y /openapi.yaml

El documento en vivo — siempre sincronizado con lo que el servidor realmente sirve. Apunta cualquier generador de cliente (sgcOpenAPI, openapi-generator, oapi-codegen) a esta URL.

/docs — Swagger UI

La familiar Swagger UI interactiva — prueba operaciones, navega esquemas, mira ejemplos. Tema, deepLinking y redirect de OAuth2 configurables.

/redoc — Redoc

El diseño limpio de tres paneles de Redoc para documentación de API con aspecto estático. Misma fuente, distinta presentación.

Formatos de cable

Negociación de Contenido Bien Hecha

application/json

UTF-8, estricto según RFC 8259. Números, booleanos, nulls, objetos anidados y arrays.

application/yaml

YAML 1.2 con parsing que conoce el esquema. Útil para cuerpos de solicitud editados a mano.

application/x-www-form-urlencoded

Posts de formulario clásicos — vinculados al esquema de la solicitud como cualquier otro cuerpo.

multipart/form-data

Subidas de archivos con límites de tamaño, listas de MIME-types permitidos y binding de esquema por parte.

text/event-stream (SSE)

Respuestas streamed de larga duración — reutiliza el writer SSE de sgcWebSockets.

application/octet-stream

Descarga/subida binaria en crudo con soporte de byte-range requests.

Integración

Un Servidor HTTP, Muchas Superficies

TsgcOpenAPIServer se conecta al mismo servidor HTTP/2 de sgcWebSockets que aloja tus endpoints WebSocket, streams de IA/LLM y archivos estáticos. Un puerto, un certificado TLS, un stream de logs.

Multiplexación HTTP/2

Cientos de operaciones REST y una suscripción WebSocket de larga duración comparten la misma conexión TLS. Los clientes de navegador obtienen un handshake en una sola ida y vuelta, y tú tienes menos sockets que mantener vivos.

Promoción a WebSocket

Declara x-sgc-upgrade: websocket en un path y el componente realiza el upgrade RFC 6455 por ti — la misma operación hace tanto REST como streaming bidireccional.

Rutas de assets estáticos

Coloca el build de la SPA bajo /app en el mismo componente — URLs limpias, gzip, brotli, ETag y server-push HTTP/2 gratis.

Dónde brilla

Despliegues Típicos

APIs REST públicas

Versionadas, probadas por contrato, con SDKs autogenerados que tus clientes pueden descargar desde /openapi.json.

Microservicios internos

Contratos servicio a servicio que sobreviven a los refactors — la spec es el test de integración.

Gateways industriales / IoT

Dispositivos edge que exponen un plano de control REST documentado más una superficie de telemetría MQTT o WebSocket desde el mismo binario Delphi.

Receptores de webhook

El payload de webhook de cada proveedor se convierte en un record Pascal tipado — Stripe, GitHub, Twilio, Slack — con validación e idempotencia integradas.

Modernización de legacy

Envuelve un backend antiguo de DataSnap o RemObjects detrás de una superficie OpenAPI limpia sin reescribir la lógica de negocio.

BFF (Backend-for-Frontend)

Agrega dos o tres APIs upstream detrás de una única spec con forma de consumidor — tu SPA o app móvil habla con un único endpoint tipado.

Mejor juntos