TsgcOpenAPIServer は、ライブの OpenAPI 3.x ドキュメントを公開し、受信リクエストを仕様に従ってルーティングし、ペイロードを双方向で検証し、Swagger UI と Redoc を内蔵で提供します — これらすべてが、sgcWebSockets HTTP/2 サーバーの上に乗る 1 つの 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、HTTP メソッド、リクエストスキーマ、レスポンススキーマ、セキュリティ)。コンポーネントは実行時に OpenAPI ドキュメントを構築し、/openapi.json に公開します。
最適なケース:迅速なプロトタイピング、社内サービス、または既存の TIdHTTPServer / DataSnap の REST 面を自己文書化 API に移行するとき。
コンポーネントをフォームに配置し、OpenAPI ドキュメントを指定し、1 つのオペレーションをバインドして 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。1 つのオペレーションに複数のキー。定数時間比較。
RFC 7617 / RFC 6750、realm サポート。資格情報は決してログに残りません。
JWKS の自動取得とキャッシュ。issuer、audience、有効期限、カスタム claim のチェック。
Authorization Code、Client Credentials、Password、Implicit フロー。PKCE 対応。
/.well-known/openid-configuration から discovery ドキュメントをロード。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 ドキュメントを実現する、Redoc の整然とした 3 ペインレイアウト。同じソース、異なる表現。
UTF-8、RFC 8259 厳格。数値、ブール値、null、ネストされたオブジェクトと配列。
スキーマを認識するパース付きの YAML 1.2。手書きのリクエストボディに便利です。
古典的なフォーム POST — 他のボディと同様にリクエストスキーマにバインドされます。
サイズ制限、MIME タイプの許可リスト、パートごとのスキーマバインディングを伴うファイルアップロード。
長時間実行されるストリーミングレスポンス — sgcWebSockets の SSE ライターを再利用します。
byte-range リクエストをサポートする生のバイナリのダウンロード/アップロード。
TsgcOpenAPIServer は、WebSocket エンドポイント、AI/LLM ストリーム、静的ファイルをホストしているのと同じ sgcWebSockets HTTP/2 サーバーに接続します。ポート 1 つ、TLS 証明書 1 つ、ログストリーム 1 つ。
何百もの REST オペレーションと長時間動作する WebSocket サブスクリプションが、同じ TLS 接続を共有します。ブラウザクライアントは 1 往復のハンドシェイクだけで済み、維持すべきソケット数も減ります。
パスに x-sgc-upgrade: websocket を宣言すれば、コンポーネントが RFC 6455 アップグレードを実行します — 同じオペレーションが REST と双方向ストリーミングの両方を担います。
同じコンポーネントの /app 配下に SPA ビルドを配置 — きれいな URL、gzip、brotli、ETag、HTTP/2 server-push を無料で。
バージョン管理、コントラクトテスト済み、自動生成された SDK は顧客が /openapi.json からダウンロードできます。
リファクタを生き延びるサービス間コントラクト — 仕様がそのまま統合テストです。
エッジデバイスが、同一の Delphi バイナリから、ドキュメント化された REST コントロールプレーンと MQTT または WebSocket のテレメトリ面を公開します。
各プロバイダの Webhook ペイロードが型付きの Pascal レコードになります — Stripe、GitHub、Twilio、Slack — 検証と冪等性が標準装備。
ビジネスロジックを書き直さずに、古い DataSnap や RemObjects のバックエンドをきれいな OpenAPI 面の背後に包み込みます。
2、3 個のアップストリーム API を、消費者の形に合わせた 1 つの仕様の背後に集約 — SPA やモバイルアプリは型付きの単一エンドポイントと対話します。
あらゆる外部仕様を、サーバーが使うのと同じモデルにロードできます — 同じ検証、同じ型システム、同じセキュリティのプリミティブ。
AWS、Azure、GCP、Stripe、GitHub、Kubernetes など向けの 1,195 以上の生成済み SDK — サーバーは同じコンポーネントファミリーで、そのいずれも呼び出せます。
WebSocket、MQTT、AMQP、WebRTC、AI/LLM、IoT — HTTP サーバーが REST 面と並べてホストできるすべて。
規制業界向けに、リクエストおよびレスポンスのボディに XAdES / PAdES / CAdES で署名 — どのオペレーションにも eIDAS グレードの完全性。