Delphi için OpenAPI Sunucusu

TsgcWSAPIServer_OpenAPI; yüklediğiniz OpenAPI 3.x belgesini sunar, gelen her isteği bu belgeyle eşleştirir, isteği işleyiciniz çalışmadan önce doğrular ve belgeyi bir Swagger UI sayfasıyla birlikte aynı porttan yayınlar. Tek bir Delphi bileşeni, bir TsgcHTTPServer'a bağlanır.

OpenAPI 3.0 ve 3.1

HTTP/2 + TLS 1.3

/docs adresinde Swagger UI

Önce spesifikasyon veya önce kod

Ücretsiz Denemeyi İndir Kodu Görün

Bir bakışta

TsgcWSAPIServer_OpenAPI

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

Bileşen sınıfı

TsgcWSAPIServer_OpenAPI, sgcWebSocket_Server_API_OpenAPI içinde tanımlanır

Barındıran sunucu

Server'a bir TsgcHTTPServer, TsgcHTTPRESTServer veya TsgcWebSocketHTTPServer atayın. Portu, bağlamaları ve TLS'yi barındıran sunucu yönetir.

Spesifikasyon biçimi

LoadFromFile ve LoadFromString ile JSON olarak okunan OpenAPI 3.0 ve 3.1 belgeleri

İki iş akışı

Elinizde zaten olan bir belgeden önce spesifikasyon, veya öznitelikli bir Delphi sınıfından önce kod. Önce kod için Delphi XE7 veya üzeri gerekir.

Sürüm

sgcOpenAPI ile birlikte gelir. sgcWebSockets içinde Enterprise sürümüne aittir, SGC OpenAPI palet sayfasında yer alır.

Yerleşik uç noktalar

Belge için /openapi.json ve Swagger UI için /docs, ikisi de OpenAPIOptions.Endpoint içinde açılır

Oluşturmanın iki yolu

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

Aynı bileşen her iki modda da çalışır. Bir JSON sözleşmesinden başlayın veya API'yi Delphi'de tanımlayın ve tarayıcının belgeyi sizin için oluşturmasına izin verin.

1. Önce spesifikasyon

petstore.json dosyasını LoadFromFile ile yükleyin, işlem kimliğine göre OnRequest içinde yönlendirin ve hizmet vermeye başlayın. Yönlendirme, yol ve sorgu parametresi bağlama ile doğrulamanın tümü sözleşmeden gelir, böylece 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

Sade bir Delphi sınıfını sgcServiceContract, sgcRoute, sgcHttpGet ve sgcFromPath / sgcFromQuery / sgcFromBody parametre öznitelikleriyle işaretleyin. TsgcOpenAPICodeFirstScanner.GenerateSpec, OpenAPI belgesini sınıfın RTTI'sinden oluşturur, siz onu LoadFromString'a verirsiniz ve aynı /openapi.json uç noktası belgeyi yayınlar.

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 oluşturun, bir belge yükleyin, bir HTTP sunucusuna bağlayın. Kurulumun tamamı budur.

Delphi

uses
  sgcHTTP_Server, sgcHTTP_OpenAPI_Server, sgcWebSocket_Server_API_OpenAPI;

procedure TForm1.FormCreate(Sender: TObject);
begin
  FServer := TsgcHTTPServer.Create(Self);
  FServer.Port := 8080;

  FOpenAPI := TsgcWSAPIServer_OpenAPI.Create(Self);
  FOpenAPI.LoadFromFile('petstore.json');      // any OpenAPI 3.x document
  FOpenAPI.OpenAPIOptions.Endpoint.ServeSpec := True;
  FOpenAPI.OpenAPIOptions.Endpoint.ServeSwaggerUI := True;
  FOpenAPI.OnRequest := OpenAPIRequest;
  FOpenAPI.Server := FServer;                // Server is the switch, there is no Active

  FServer.Active := True;
end;

// one event, dispatched by operation id
procedure TForm1.OpenAPIRequest(Sender: TObject;
  const aOperationId: string;
  const aContext: TsgcOpenAPIServerContext;
  var Handled: Boolean);
begin
  Handled := True;
  if aOperationId = 'getPetById' then
    aContext.RespondJSON(200, FPets.Values[aContext.PathParamAsString('petId')])
  else
    Handled := False;
end;

Kutudan çıktığı gibi neler elde edersiniz: GET /pets/{petId} yukarıdaki işleyiciye aOperationId değeri getPetById olarak ulaşır, GET /openapi.json yüklediğiniz belgeyi döndürür, GET /docs Swagger UI'yi açar. OpenAPIOptions.Endpoint.BasePath, tüm yüzeyi bir önek altına taşır ve TLS ile HTTP/2 barındıran sunucudan gelir.

Yönlendirme

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

OpenAPI belgesinde bildirilen parametreler, tek bir tipli bağlam aracılığıyla okunur ve dönüştürülür. Doğrulama açıkken, yanlış bir tip, işleyiciniz çalışmadan önce 400 Bad Request ile yanıtlanı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

procedure TForm1.HandleListPets(const aContext: TsgcOpenAPIServerContext);
var
  vLimit:  Integer;
  vStatus: string;
  vTenant: string;
begin
  vLimit  := aContext.QueryParamAsInteger('limit', 20);        // default 20
  vStatus := aContext.QueryParamAsString ('status', 'available');
  vTenant := aContext.HeaderValue        ('X-Tenant-Id');   // required in the spec

  aContext.RespondJSON(200, PetRepo.List(vTenant, vStatus, vLimit));
end;

Doğrulama

İşleyiciniz Çalışmadan Önce Şema Doğrulaması

Gelen her istek, belgenin bildirdiği şemalara göre kontrol edilir. Bir hata, her bir hatayı listeleyen RFC 7807 tarzı bir problem belgesiyle yanıtlanır ve siz izin vermedikçe işleyicinize asla ulaşmaz.

Neyin kontrol edildiği

type, required, properties ve additionalProperties, enum ve const, minLength / maxLength, pattern, kendi exclusive biçimleriyle birlikte minimum / maximum, multipleOf, items, minItems / maxItems, uniqueItems, nullable, not ve oneOf / anyOf / allOf. format anahtar sözcüğü date, date-time, email, ipv4, uri ve uuid için uygulanır.

Kapsamı seçin

Validation.ValidateRequest ana anahtardır ve tek başına her kapsamı doğrular. Bunu ValidateRequestBody, ValidateQueryParams, ValidatePathParams, ValidateHeaderParams ve ValidateCookieParams ile daraltın. EnforceRequired, seçtiğiniz kapsamda etkili kalır.

Son sözü siz söyleyin

OnValidationError size işlem kimliğini ve hataların tam listesini verir. Continue bayrağı False olarak gelir, bu yüzden siz kasıtlı olarak True yapmadıkça istek reddedilir. Her yüklemeden sonra Validation.Warnings, belgenin kullandığı ama uygulanmayan her şema anahtar sözcüğünü adlandırır, boş bir liste hiçbir şeyin kontrolsüz kalmadığı anlamına gelir.

JSON, motorun yazdığı 400

{
  "type":   "about:blank",
  "title":  "Bad Request",
  "status": 400,
  "detail": "Request validation failed",
  "errors": [
    "/email: invalid email format",
    "/age: must be <= 120",
    "/status: value not in enum"
  ]
}

Güvenlik

Spesifikasyonun Yönlendirdiği Kimlik Doğrulama Şemaları

Security.EnforceSecurity'yi ayarlayın, belgenin bildirdiği securitySchemes gelen isteklere uygulanır. Siz kimlik bilgisi aramasını yazarsınız, bileşen isteği ayrıştırır ve arama hayır dediğinde 401 veya 403 ile yanıtlar.

API Anahtarı

Şemanın belirttiğine göre bir başlıktan, bir sorgu parametresinden veya bir çerezden okunur. OnValidateAPIKey şemayı, adı, konumu ve anahtarı alır ve Valid üzerinden yanıt verir.

HTTP Basic

Authorization başlığı sizin için ayrıştırılır. OnValidateBasic kullanıcı adını ve parolayı alır ve Valid üzerinden yanıt verir. Kimlik bilgileri asla günlüğe yazılmaz.

Bearer ve JWT

Security.JWTSecret belirteci doğrular. Bir HMAC gizli anahtarı olduğu gibi kullanılır, -----BEGIN içeren bir değer ise bir PEM ortak anahtarı olarak ele alınır. ValidateExpiration, Issuer ve Audience talepleri kontrol eder.

Kendi doğrulayıcınız

JWTSecret'i boş bırakın, belirteç yalnızca varlığı açısından kontrol edilir, böylece OnValidateBearer onu kendi belirteç servisinize teslim edebilir ve Valid üzerinden yanıt verebilir.

401 mi 403 mü

Başarısız bir istek 401 ile yanıtlanır, yalnızca kapsam bakımından yetersiz kalıp kimliği doğrulanmışsa 403 ile yanıtlanır. OnAuthenticate önce çalışır ve Authenticated'ı temizlediğiniz an 401 ile reddeder.

Kod Yazılmadan Önce Mock

Mock.Enabled, işleyicisi olmayan bir işlemi belgenin kendi örneklerinden ve şemalarından, Mock.StatusCode ile yanıtlar, böylece bir ön yüz ekibi uygulama yazılırken çalışabilir.

Delphi, kendi kodunuzla doğrulanan bearer token

FOpenAPI.OpenAPIOptions.Security.EnforceSecurity := True;
FOpenAPI.OpenAPIOptions.Security.JWTSecret := GetSecretFromEnvironment;
FOpenAPI.OpenAPIOptions.Security.ValidateExpiration := True;
FOpenAPI.OpenAPIOptions.Security.Issuer   := 'https://auth.example.com';
FOpenAPI.OpenAPIOptions.Security.Audience := 'api.example.com';
FOpenAPI.OnValidateBearer := OpenAPIValidateBearer;

procedure TForm1.OpenAPIValidateBearer(Sender: TObject;
  const aToken: string;
  const aContext: TsgcOpenAPIServerContext; var Valid: Boolean);
begin
  Valid := MyTokenService.Verify(aToken);
end;

Kendi kendini belgeleyen

Gömülü Swagger UI

Dağıtım hattında harici bağımlılık, Node.js veya belge derleme adımı yok. Sayfayı bileşenin kendisi yazar ve sunucunuzun gerçekte sunduğu belgeyi okur.

/openapi.json

Yüklediğiniz belge, Endpoint.ServeSpec açıkken sunulur. Sunucunun gerçekte yönlendirdiğiyle her zaman uyumludur. Herhangi bir istemci üreticisini, sgcOpenAPI dahil, bu URL'ye yönlendirin.

/docs

Etkileşimli Swagger UI sayfası, Endpoint.ServeSwaggerUI açıkken sunulur. İşlemleri deneyin, şemalara göz atın, örnekleri okuyun, hepsi kendi çalışan sunucunuzdan beslenir.

Sabitlenmiş veya tamamen çevrimdışı

Sayfa, CSS ve JavaScript dosyalarını varsayılan olarak genel bir CDN'den yükler. Endpoint.SwaggerUIBaseURL bir sürümü sabitler, Endpoint.SwaggerUIAssetsPath ise swagger-ui.css ve swagger-ui-bundle.js dosyalarını yerel bir klasörden sunar, böylece internete kapalı bir makinede de çalışır.

Yapılandırma

Her Şey OpenAPIOptions Altında Yaşar

Nesne Denetleyicisi'nde görünen, çalışma zamanında atanabilen beş kalıcı alt nesne.

Endpoint

BasePath her yolun ve iki yerleşik uç noktanın önüne eklenir. ServeSpec ve ServeSwaggerUI bunları açıp kapatır. SpecFile, ikisinden biri olmayan ilk istekte tembelce yüklenir, bu yüzden belgenin ilk çağrıdan itibaren tam olması gerekiyorsa LoadFromFile kullanın.

Validation

ValidateRequest ve beş kapsam anahtarı, ayrıca EnforceRequired. Warnings, her yüklemeden sonra belgenin kullandığı ama bu doğrulayıcının uygulamadığı şema anahtar sözcüklerini bildirir.

CORS

Enabled, AllowOrigins, AllowHeaders ve AllowMethods. Motor, yanıtları kendi belgesine ait yollara damgalar, bu yüzden barındıran sunucuya sahip olduğu yollar için aynı değerleri verin.

Security

EnforceSecurity, JWTSecret, ValidateExpiration, Issuer ve Audience. Yerleşik kontrollerin karar veremediği her şey OnValidateAPIKey, OnValidateBasic veya OnValidateBearer'a ulaşır.

Mock

Enabled ve StatusCode. İşleyicisi olmayan bir işlem, belgenin kendi örneklerinden ve şemalarından yanıtlanır, böylece sözleşme uygulama var olmadan önce çağrılabilir.

Kasıtlı Olarak Uygulanmadı

Handled'ı False bırakın, motor bir yönlendirme hatası gibi görünen 404 yerine işlemi adlandırarak 501 Not Implemented yanıtı verir.

Entegrasyon

Tek HTTP Sunucusu, Birçok Yüzey

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

Anahtar, Server'dır

Bileşende Active özelliği yoktur. Server'a bir değer atamak bileşeni bağlar, nil atamak ise barındıran sunucu çalışmaya devam ederken bağlantıyı keser. Bağlantı kesildiğinde, belgesine ait yollar doğrudan sizin sıradan işleyicinize düşer.

Sunucuyu Asla Ele Geçirmez

Her istek önce bileşene sunulur ve bileşen yalnızca kendi belgesinin bildirdiği yolları yanıtlar. Geri kalan her şey eskisi gibi OnCommandGet'e ulaşır, böylece sözleşme öncelikli bir bölüm, elle yazılmış rotaların ve DocumentRoot'tan gelen statik içeriğin yanında, hepsi tek bir portta bir arada yaşar.

Barındıran Sunucunun TLS'i ve HTTP/2'si

Port, bağlamalar, sertifika ve HTTP/2 anlaşması barındıran sunucuya aittir, bu yüzden REST yüzeyi bunları değişmeden devralır. Onu bir TsgcHTTPRESTServer'a bağlayın, o sunucunun CORS, metrikler, sağlık ve kiracılık özellikleri de geçerli olur.

Ö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

All-Access fiyatlarına bakın