TsgcOpenAPIServer는 살아있는 OpenAPI 3.x 문서를 게시하고, 들어오는 요청을 스펙에 따라 라우팅하며, 양방향으로 페이로드를 검증하고, Swagger UI와 Redoc을 임베드 형태로 제공합니다 — 이 모든 것이 sgcWebSockets HTTP/2 서버 위에 얹은 하나의 Delphi 컴포넌트에서 이루어집니다.
OpenAPI 명세를 실행 중이고, 검증되며, 스스로 문서화되는 HTTP/2 서버로 바꿔주는 단 하나의 Delphi 컴포넌트.
TsgcOpenAPIServer
HTTP/1.1, HTTP/2, WebSocket 업그레이드, OpenSSL 또는 SChannel을 통한 TLS
OpenAPI 3.0, OpenAPI 3.1, Swagger 2.0(자동 변환)
Windows, Linux, macOS — Delphi 7부터 13까지, C++Builder, FPC
Standard / Professional / Enterprise — 모두 서버 포함
sgcWebSockets HTTP 서버(동일한 TLS, HTTP/2, 인증, 로깅 파이프라인)
동일한 컴포넌트가 두 모드 모두에서 동작합니다. YAML/JSON 계약에서 시작하거나, Delphi에서 API를 설명하고 컴포넌트가 스펙을 대신 게시하도록 하세요.
openapi.yaml을 로드하고, 핸들러를 operation ID에 바인딩한 뒤 서비스를 시작하세요. 라우트, 파라미터 바인딩, 콘텐츠 협상, 검증이 모두 계약에서 곧바로 나옵니다 — 여러분은 비즈니스 로직만 작성합니다.
적합한 경우: 공유된 디자인 계약이 있는 팀, API-led 통합, 또는 스펙이 진실의 원천인 다중 언어 백엔드.
Pascal에서 어노테이션과 함께 핸들러를 등록하세요(path, verb, 요청 스키마, 응답 스키마, 보안). 컴포넌트는 런타임에 OpenAPI 문서를 만들고 /openapi.json에 노출합니다.
적합한 경우: 빠른 프로토타이핑, 내부 서비스, 또는 기존 TIdHTTPServer / DataSnap REST 표면을 자기 문서화 API로 포팅할 때.
폼에 컴포넌트를 떨어뜨리고, OpenAPI 문서를 가리키게 하고, 작업 하나를 바인딩한 뒤 Run을 누르세요. 그것이 전체 설정입니다.
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;
기본 제공되는 것:
GET /pets/{petId}는 위의 핸들러를 서빙하고,
GET /openapi.json은 실시간 스펙을 반환하며,
GET /docs는 Swagger UI를 열고,
GET /redoc은 Redoc을 엽니다 — sgcHTTPServer1에서 HTTP/2와 TLS가 구성되어 있다면 이미 활성화된 채로 제공됩니다.
OpenAPI 문서에 선언된 파라미터는 파싱되고 타입 검사가 이루어지며 단일 타입화 컨텍스트를 통해 노출됩니다. 잘못된 타입은 핸들러가 실행되기도 전에 400 Bad Request를 반환합니다.
// 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;
들어오는 모든 본문은 해당 작업의 requestBody 스키마에 대해 검증됩니다. 모든 응답은 선언된 상태 코드에 대해 검증됩니다. 불일치는 RFC 7807 problem-details로 필드 수준의 진단과 함께 반환됩니다.
필수 필드, 타입 강제 변환, enum 멤버십, format 검증기(email, uuid, date-time, ipv4/6), minLength / maxLength, minimum / maximum, pattern, additionalProperties, oneOf / anyOf / allOf — 모두 핸들러가 실행되기 전에 적용됩니다.
운영 환경에서는 선택적, 개발 환경에서는 엄격합니다. 핸들러가 계약에 없는 추가 필드를 반환하기 시작하는 날을 다운스트림 소비자가 망가지기 전에 잡아내도록 도와줍니다.
OnBeforeValidate에 후크하여 도메인 규칙을 추가하세요(통화 코드가 지원됨, SKU 존재함, 테넌트가 활성 상태임). 통일된 오류 UX를 위해 내장 검증기와 동일한 RFC 7807 봉투를 반환합니다.
{
"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]" }
]
}
문서에 선언된 모든 securityScheme은 자동으로 적용됩니다. 여러분은 자격 증명 조회만 작성하면 됩니다 — 파싱, challenge 헤더, 401/403 응답은 컴포넌트가 처리합니다.
Header, query 또는 cookie. 작업당 다중 키. 상수 시간 비교.
RFC 7617 / RFC 6750, realm 지원. 자격 증명은 절대 로깅되지 않습니다.
JWKS 자동 페치 및 캐시. issuer, audience, 만료, 사용자 정의 claim 검사.
Authorization Code, Client Credentials, Password, Implicit 플로우. PKCE 지원.
/.well-known/openid-configuration에서 디스커버리 문서 로드. ID 토큰은 JWKS에 대해 검증.
작업별 클라이언트 인증서 적용. Common Name과 SAN을 컨텍스트에서 사용 가능.
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;
외부 종속성도, Node.js도, 배포 파이프라인에 swagger-codegen을 둘 필요도 없습니다. 두 UI 모두 컴포넌트 내부에 번들로 포함되어 런타임에 스펙에서 바로 서빙됩니다.
실시간 문서 — 서버가 실제로 서빙하는 내용과 항상 동기화됩니다. 어떤 클라이언트 생성기(sgcOpenAPI, openapi-generator, oapi-codegen)든 이 URL을 가리키게 하세요.
익숙한 인터랙티브 Swagger UI — 작업을 직접 호출하고, 스키마를 탐색하고, 예제를 확인하세요. 테마, deepLinking, OAuth2 리다이렉트가 구성 가능합니다.
정적 느낌의 API 문서를 위한 깔끔한 3패널 Redoc 레이아웃. 같은 소스, 다른 표현.
UTF-8, RFC 8259 엄격. 숫자, 불리언, null, 중첩 객체, 배열.
스키마 인식 파싱이 적용된 YAML 1.2. 사람이 직접 편집한 요청 본문에 유용합니다.
고전적인 폼 POST — 다른 본문과 마찬가지로 요청 스키마에 바인딩됩니다.
크기 제한, MIME 타입 허용 목록, 파트별 스키마 바인딩이 적용되는 파일 업로드.
오래 지속되는 스트림 응답 — sgcWebSockets의 SSE writer를 재사용합니다.
byte-range 요청을 지원하는 원시 바이너리 다운로드/업로드.
TsgcOpenAPIServer는 WebSocket 엔드포인트, AI/LLM 스트림, 정적 파일을 호스팅하는 동일한 sgcWebSockets HTTP/2 서버에 플러그인됩니다. 포트 하나, TLS 인증서 하나, 로그 스트림 하나.
수백 개의 REST 작업과 장기 실행 WebSocket 구독이 동일한 TLS 연결을 공유합니다. 브라우저 클라이언트는 한 번의 왕복 핸드셰이크로 끝나고, 여러분은 유지해야 할 소켓이 줄어듭니다.
경로에 x-sgc-upgrade: websocket을 선언하면 컴포넌트가 RFC 6455 업그레이드를 수행해 줍니다 — 같은 작업이 REST와 양방향 스트리밍을 모두 처리합니다.
동일 컴포넌트의 /app 아래에 SPA 빌드를 두세요 — 깔끔한 URL, gzip, brotli, ETag, HTTP/2 server-push가 무료로 따라옵니다.
버전 관리되고 계약으로 테스트되며, 고객이 /openapi.json에서 다운로드할 수 있는 자동 생성 SDK 제공.
리팩토링에서도 살아남는 서비스 간 계약 — 스펙이 곧 통합 테스트입니다.
동일한 Delphi 바이너리에서 문서화된 REST 제어 평면과 MQTT 또는 WebSocket 텔레메트리 표면을 함께 노출하는 엣지 디바이스.
각 공급자의 웹훅 페이로드가 타입화된 Pascal 레코드가 됩니다 — Stripe, GitHub, Twilio, Slack — 검증과 멱등성이 기본 내장됩니다.
비즈니스 로직을 다시 작성하지 않고도 오래된 DataSnap 또는 RemObjects 백엔드를 깔끔한 OpenAPI 표면 뒤로 감싸세요.
두세 개의 업스트림 API를 소비자에 맞춘 하나의 스펙 뒤로 집계하세요 — SPA나 모바일 앱은 단일 타입 엔드포인트와 대화합니다.
외부 스펙을 서버가 사용하는 동일한 모델에 로드하세요 — 동일한 검증, 동일한 타입 시스템, 동일한 보안 프리미티브.
AWS, Azure, GCP, Stripe, GitHub, Kubernetes 등을 위한 1,195개 이상의 생성된 SDK — 서버는 동일한 컴포넌트 패밀리로 이들 중 어느 것이든 호출할 수 있습니다.
WebSocket, MQTT, AMQP, WebRTC, AI/LLM, IoT — HTTP 서버가 REST 표면과 나란히 호스팅할 수 있는 모든 것.
규제 산업을 위해 XAdES / PAdES / CAdES로 요청 및 응답 본문에 서명하세요 — 모든 작업에 eIDAS급 무결성.