一个 Delphi 组件,将 OpenAPI 规范转化为运行中、经过校验、自文档化的 HTTP/2 服务器。
TsgcOpenAPIServer
HTTP/1.1、HTTP/2、WebSocket 升级,TLS 通过 OpenSSL 或 SChannel
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 动词、请求 schema、响应 schema、安全)。组件在运行时构建 OpenAPI 文档,并在 /openapi.json 上暴露。
最适合:快速原型设计、内部服务,或将现有的 TIdHTTPServer / DataSnap REST 接口迁移到自文档化的 API。
把组件拖到 form 上,指向一个 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 schema 进行校验。每个响应都会根据声明的状态码进行校验。不匹配时返回 RFC 7807 problem-details,带有字段级诊断。
必填字段、类型转换、枚举成员、format 校验器(email、uuid、date-time、ipv4/6)、minLength / maxLength、minimum / maximum、pattern、additionalProperties、oneOf / anyOf / allOf — 全部在你的处理器运行之前强制执行。
生产环境可选,开发环境严格。帮你提前发现处理器返回了契约中没有的额外字段的那一天,防止下游消费者出错。
挂接 OnBeforeValidate 来添加业务规则(币种代码受支持、SKU 存在、租户处于活跃状态)。返回与内置校验器相同的 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。每个操作支持多个 key。常量时间比较。
RFC 7617 / RFC 6750,支持 realm。凭据永不入日志。
JWKS 自动拉取并缓存。issuer、audience、过期时间和自定义 claim 检查。
Authorization Code、Client Credentials、Password 和 Implicit 流。支持 PKCE。
从 /.well-known/openid-configuration 加载 discovery 文档。ID token 对 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 — 试用操作、浏览 schema、查看示例。可配置主题、deepLinking 和 OAuth2 重定向。
简洁的三栏 Redoc 布局,提供静态风格的 API 文档。同一来源,不同呈现。
UTF-8,严格遵守 RFC 8259。数字、布尔、null、嵌套对象与数组。
YAML 1.2,带有感知 schema 的解析。适合人工编辑的请求体。
经典表单 POST — 像其他任何请求体一样绑定到请求 schema。
文件上传,支持大小限制、MIME 类型白名单和按 part 的 schema 绑定。
长时间运行的流式响应 — 复用 sgcWebSockets 的 SSE writer。
原始二进制下载/上传,支持 byte-range 请求。
TsgcOpenAPIServer 接入与 WebSocket 端点、AI/LLM 流和静态文件相同的 sgcWebSockets HTTP/2 服务器。一个端口、一份 TLS 证书、一条日志流。
数百个 REST 操作和一个长连接的 WebSocket 订阅共享同一条 TLS 连接。浏览器客户端只需要一次往返握手,你需要维持的 socket 也更少。
在路径上声明 x-sgc-upgrade: websocket,组件会替你执行 RFC 6455 升级 — 同一个操作同时承担 REST 和双向流式通信。
把 SPA 构建产物放到同一个组件的 /app 下 — 干净 URL、gzip、brotli、ETag 和 HTTP/2 server-push 全部免费。
带版本、契约测试,自动生成的 SDK 可供客户从 /openapi.json 下载。
能挺过重构的服务间契约 — 规范就是集成测试。
边缘设备从同一个 Delphi 二进制文件中既暴露文档化的 REST 控制面,又暴露 MQTT 或 WebSocket 遥测接口。
每个供应商的 webhook 载荷都变成类型化的 Pascal 记录 — Stripe、GitHub、Twilio、Slack — 内置校验与幂等性。
在不重写业务逻辑的前提下,把老旧的 DataSnap 或 RemObjects 后端包装在干净的 OpenAPI 接口之后。
把两三个上游 API 聚合到一份贴合消费者形态的规范背后 — 你的 SPA 或移动 App 只与一个类型化的端点对话。
把任意外部规范加载到与服务器使用的同一模型中 — 相同的校验、相同的类型系统、相同的安全原语。
1,195+ 个为 AWS、Azure、GCP、Stripe、GitHub、Kubernetes 等生成的 SDK — 你的服务器可以用同一族组件调用任何一个。
WebSocket、MQTT、AMQP、WebRTC、AI/LLM、IoT — HTTP 服务器能与你的 REST 接口一同承载的一切。
用 XAdES / PAdES / CAdES 对请求和响应体进行签名,面向受监管行业 — 每个操作都具有 eIDAS 级别的完整性。