Delphi için OpenAPI Sunucusu

Bir bakışta

TsgcOpenAPIServer

Bir OpenAPI spesifikasyonunu çalışan, doğrulanmış, kendi kendini belgeleyen bir HTTP/2 sunucusuna dönüştüren tek bir Delphi bileşeni.

Bileşen sınıfı

TsgcOpenAPIServer

Taşıma

HTTP/1.1, HTTP/2, WebSocket yükseltmesi, OpenSSL veya SChannel aracılığıyla TLS

Spesifikasyon biçimleri

OpenAPI 3.0, OpenAPI 3.1, Swagger 2.0 (otomatik dönüştürülür)

Platformlar

Windows, Linux, macOS — Delphi 7'den 13'e, C++Builder, FPC

Sürüm

Standard / Professional / Enterprise — tümü sunucuyu içerir

Üzerine kurulu

sgcWebSockets HTTP sunucusu (aynı TLS, HTTP/2, kimlik doğrulama ve günlükleme hattı)

Oluşturmanın iki yolu

Önce Spesifikasyon veya Önce Kod — Siz Seçin

Aynı bileşen her iki modda da çalışır. Bir YAML/JSON sözleşmesinden başlayın veya API'yi Delphi'de tanımlayın ve bileşenin spesifikasyonu sizin için yayınlamasına izin verin.

1. Önce spesifikasyon

openapi.yaml dosyasını yükleyin, işleyicileri işlem kimliklerine bağlayın ve hizmet vermeye başlayın. Yollar, parametre bağlama, içerik anlaşması ve doğrulama doğrudan sözleşmeden gelir — siz yalnızca iş mantığını yazarsınız.

En uygun: ortak bir tasarım sözleşmesine sahip ekipler, API odaklı entegrasyon veya spesifikasyonun doğruluk kaynağı olduğu çok dilli arka uçlar için.

2. Önce kod

İşleyicileri Pascal'da açıklamalarla (yol, fiil, istek şeması, yanıt şeması, güvenlik) kaydedin. Bileşen, OpenAPI belgesini çalışma zamanında oluşturur ve /openapi.json üzerinde sunar.

En uygun: hızlı prototip oluşturma, dahili hizmetler veya mevcut bir TIdHTTPServer / DataSnap REST yüzeyini kendi kendini belgeleyen bir API'ye taşıma için.

Hızlı Başlangıç

20 Satırda Çalışan Bir Sunucu

Bileşeni bir forma bırakın, bir OpenAPI belgesine yönlendirin, bir işlem bağlayın, Çalıştır'a basın. Kurulumun tamamı budur.

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;

Kutudan çıktığı gibi neler elde edersiniz: GET /pets/{petId} yukarıdaki işleyiciyi sunar, GET /openapi.json canlı spesifikasyonu döndürür, GET /docs Swagger UI'yi açar, GET /redoc Redoc'u açar — sgcHTTPServer1 yapılandırılmışsa HTTP/2 ve TLS zaten etkin olarak.

Yönlendirme

Yol, Sorgu, Başlık ve Çerez Parametreleri — Tümü Tipli

OpenAPI belgesinde bildirilen parametreler ayrıştırılır, tip kontrolünden geçirilir ve tek bir tipli bağlam aracılığıyla sunulur. Yanlış tipler, işleyiciniz çalışmadan önce 400 Bad Request döndürür.

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;

Doğrulama

Her İki Yönde Şema Doğrulaması

Gelen her gövde, işlemin requestBody şemasına göre doğrulanır. Her yanıt, bildirilen durum koduna göre doğrulanır. Uyumsuzluklar, alan düzeyinde tanılamalarla RFC 7807 problem ayrıntıları döndürür.

İstek doğrulaması

Zorunlu alanlar, tip zorlaması, enum üyeliği, format doğrulayıcıları (email, uuid, date-time, ipv4/6), minLength / maxLength, minimum / maximum, pattern, additionalProperties, oneOf / anyOf / allOf — tümü işleyiciniz çalışmadan önce uygulanır.

Yanıt doğrulaması

Üretimde isteğe bağlı, geliştirmede katı. İşleyicinizin sözleşmede olmayan ekstra bir alan döndürdüğü günü, bir alt tüketici bozulmadan önce yakalamanıza yardımcı olur.

Özel doğrulayıcılar

Alan kuralları (para birimi kodu destekleniyor, SKU mevcut, kiracı etkin) eklemek için OnBeforeValidate kancasına bağlanın. Tek tip hata kullanıcı deneyimi için yerleşik doğrulayıcılarla aynı RFC 7807 zarfını döndürür.

JSON — örnek 400 yanıtı

{
  "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]" }
  ]
}

Güvenlik

Spesifikasyondan Bağlanmış Kimlik Doğrulama Şemaları

Belgede bildirilen her securityScheme otomatik olarak uygulanır. Siz yalnızca kimlik bilgisi aramasını yazarsınız — bileşen ayrıştırmayı, challenge başlıklarını ve 401/403 yanıtlarını yapar.

API Anahtarı

Başlık, sorgu veya çerez. İşlem başına birden fazla anahtar. Sabit zamanlı karşılaştırma.

HTTP Basic / Bearer

Realm desteğiyle RFC 7617 / RFC 6750. Kimlik bilgileri asla günlüğe kaydedilmez.

JWT (RS256 / ES256 / HS256)

JWKS otomatik getirme ve önbellek. Issuer, audience, süre dolumu ve özel talep kontrolleri.

OAuth2

Authorization Code, Client Credentials, Password ve Implicit akışları. PKCE desteklenir.

OpenID Connect

Keşif belgesi /.well-known/openid-configuration adresinden yüklenir. ID belirteci JWKS'ye göre doğrulanır.

mTLS

İşlem başına istemci sertifikası uygulaması. Bağlamda Common Name ve SAN çıkarımı mevcuttur.

Delphi — JWT doğrulama kancası

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;

Kendi kendini belgeleyen

Gömülü Swagger UI ve Redoc

Dağıtım hattında harici bağımlılık, Node.js veya swagger-codegen yok. Her iki kullanıcı arayüzü de bileşenin içine pakettenir ve çalışma zamanında doğrudan spesifikasyondan sunulur.

/openapi.json ve /openapi.yaml

Canlı belge — her zaman sunucunun gerçekte sunduğuyla senkronize. Herhangi bir istemci üreticisini (sgcOpenAPI, openapi-generator, oapi-codegen) bu URL'ye yönlendirin.

/docs — Swagger UI

Tanıdık etkileşimli Swagger UI — işlemleri deneyin, şemalara göz atın, örnekleri görün. Yapılandırılabilir tema, deepLinking ve OAuth2 yönlendirmesi.

/redoc — Redoc

Statik hissiyatlı API belgeleri için temiz, üç bölmeli Redoc düzeni. Aynı kaynak, farklı sunum.

Veri biçimleri

Doğru Yapılan İçerik Anlaşması

application/json

UTF-8, RFC 8259 katı. Sayılar, boolean'lar, null'lar, iç içe nesneler ve diziler.

application/yaml

Şema farkında ayrıştırmayla YAML 1.2. İnsan tarafından düzenlenen istek gövdeleri için yararlıdır.

application/x-www-form-urlencoded

Klasik form gönderileri — diğer herhangi bir gövde gibi istek şemasına bağlanır.

multipart/form-data

Boyut sınırları, MIME türü izin listeleri ve bölüm başına şema bağlamayla dosya yüklemeleri.

text/event-stream (SSE)

Uzun süre çalışan akışlı yanıtlar — sgcWebSockets SSE yazıcısını yeniden kullanır.

application/octet-stream

Bayt aralığı isteği desteğiyle ham ikili indirme / yükleme.

Entegrasyon

Tek HTTP Sunucusu, Birçok Yüzey

TsgcOpenAPIServer, WebSocket uç noktalarınızı, AI/LLM akışlarınızı ve statik dosyalarınızı barındıran aynı sgcWebSockets HTTP/2 sunucusuna bağlanır. Tek port, tek TLS sertifikası, tek günlük akışı.

HTTP/2 çoğullama

Yüzlerce REST işlemi ve uzun ömürlü bir WebSocket aboneliği aynı TLS bağlantısını paylaşır. Tarayıcı istemcileri tek gidiş-dönüş el sıkışması alır, siz canlı tutulacak daha az soket elde edersiniz.

WebSocket yükseltmesi

Bir yolda x-sgc-upgrade: websocket bildirin; bileşen RFC 6455 yükseltmesini sizin için gerçekleştirir — aynı işlem hem REST hem de çift yönlü akış yapar.

Statik varlık yolları

SPA derlemesini aynı bileşende /app altına bırakın — temiz URL'ler, gzip, brotli, ETag ve HTTP/2 server-push ücretsiz.

Öne çıktığı yerler

Tipik Dağıtımlar

Herkese açık REST API'leri

Sürümlü, sözleşme test edilmiş ve müşterilerinizin /openapi.json adresinden indirebileceği otomatik üretilmiş SDK'lerle.

Dahili mikro hizmetler

Yeniden düzenlemelerden sağ çıkan hizmetten hizmete sözleşmeler — spesifikasyon entegrasyon testidir.

Endüstriyel / IoT ağ geçitleri

Aynı Delphi ikili dosyasından belgelenmiş bir REST kontrol düzlemi ile bir MQTT veya WebSocket telemetri yüzeyi sunan uç cihazlar.

Webhook alıcıları

Her sağlayıcının webhook yükü, doğrulama ve idempotency yerleşik olarak tipli bir Pascal kaydı olur — Stripe, GitHub, Twilio, Slack.

Eski sistem modernizasyonu

İş mantığını yeniden yazmadan eski bir DataSnap veya RemObjects arka ucunu temiz bir OpenAPI yüzeyinin arkasına sarın.

BFF (Backend-for-Frontend)

İki veya üç yukarı akış API'sini tek bir tüketici biçimli spesifikasyonun arkasında birleştirin — SPA'nız veya mobil uygulamanız tek, tipli bir uç noktayla konuşur.

Birlikte daha iyi