OpenAPI-server
Host een OpenAPI 3 REST-API rechtstreeks binnen een Delphi HTTP-server. Spec-first of code-first, met automatische Swagger UI, requestvalidatie en CORS — de spec wordt de enige bron van waarheid.
Host een OpenAPI 3 REST-API rechtstreeks binnen een Delphi HTTP-server. Spec-first of code-first, met automatische Swagger UI, requestvalidatie en CORS — de spec wordt de enige bron van waarheid.
Een drop-in API-server die in TsgcWebSocketHTTPServer wordt geplugd, een OpenAPI 3-spec laadt (of er een genereert uit geannoteerde Pascal-klassen) en binnenkomende requests dispatcht op basis van operationId.
TsgcWSAPIServer_OpenAPI
Windows, macOS, Linux, iOS, Android
Enterprise
Maak het component aan, laad (of genereer) een spec en koppel het aan een HTTP-server. Het component matcht routes, valideert invoer en serveert Swagger UI automatisch op /docs.
uses
sgcWebSocket, sgcWebSocket_Server_API_OpenAPI,
sgcHTTP_OpenAPI_Server;
var
Server: TsgcWebSocketHTTPServer;
OpenAPI: TsgcWSAPIServer_OpenAPI;
begin
Server := TsgcWebSocketHTTPServer.Create(nil);
Server.Port := 8080;
OpenAPI := TsgcWSAPIServer_OpenAPI.Create(nil);
OpenAPI.OnRequest := HandleRequest;
OpenAPI.OpenAPIOptions.Endpoint.ServeSwaggerUI := True;
OpenAPI.OpenAPIOptions.Validation.ValidateRequest := True;
OpenAPI.OpenAPIOptions.CORS.Enabled := True;
OpenAPI.LoadFromFile('petstore.json');
OpenAPI.Server := Server;
Server.Active := True;
// Swagger UI: http://localhost:8080/docs
// Raw spec: http://localhost:8080/openapi.json
end;
procedure THost.HandleRequest(Sender: TObject;
const aOperationId: string;
const aContext: TsgcOpenAPIServerContext;
var Handled: Boolean);
begin
Handled := True;
if aOperationId = 'getPetById' then
aContext.RespondJSON(200, PetAsJSON(aContext.PathParamAsInteger('petId')))
else
Handled := False;
end;uses
sgcWebSocket_Server_API_OpenAPI,
sgcHTTP_OpenAPI_Server_CodeFirst;
type
[sgcServiceContract('Task Manager', '', '1.0.0')]
[sgcRoute('/api/v1')]
TTaskService = class
public
[sgcHttpGet] [sgcRoute('/tasks/{taskId}')]
[sgcSummary('Get a task by ID')]
[sgcResponse(200, 'The requested task')]
[sgcResponse(404, 'Task not found')]
procedure GetTask([sgcFromPath][sgcRequired] const taskId: Integer); virtual;
end;
// Generate the spec from RTTI and feed it to the component:
var
Scanner: TsgcOpenAPICodeFirstScanner;
begin
Scanner := TsgcOpenAPICodeFirstScanner.Create;
try
OpenAPI.LoadFromString(Scanner.GenerateSpec(TTaskService));
finally
Scanner.Free;
end;
OpenAPI.Server := Server;
Server.Active := True;
end;Twee manieren om een API te definiëren, vier pipeline-hooks, validatie tegen de spec en een Swagger UI-pagina die door het component zelf wordt geserveerd.
Laad een bestaand OpenAPI 3-document met LoadFromFile of LoadFromString. Routes, parameters en schema's worden geparseerd en vormen het contract dat je server moet respecteren — wijzig de JSON, herstart, klaar.
Annoteer Pascal-klassen met sgcHttpGet- / sgcRoute- / sgcFromPath- / sgcResponse-attributen; TsgcOpenAPICodeFirstScanner doorloopt de RTTI en genereert de spec tijdens runtime — geen JSON die je met de hand hoeft te schrijven.
Zet OpenAPIOptions.Endpoint.ServeSwaggerUI aan en de server publiceert een interactieve try-it-out-pagina op /docs, gevoed door /openapi.json — geen aparte docs-build, geen statische export.
Valideert de body, querystring, padparameters en verplichte velden tegen de schema's in de spec. Bij een fout geeft OnValidationError je de volledige foutenlijst en een Continue-vlag om te weigeren of door te gaan.
Zet OpenAPIOptions.CORS.Enabled := True en de server beantwoordt preflight-OPTIONS op elke route, met toepassing van je AllowOrigins- / AllowHeaders- / AllowMethods-beleid.
TsgcOpenAPIServerContext stelt PathParamAs*, QueryParamAs*, HeaderValue, BodyAsString / BodyAsJSON beschikbaar plus RespondJSON en een RespondError in RFC 7807-stijl.
OnBeforeRequest, OnAfterRequest, OnAuthenticate en OnException omhullen de hoofd-OnRequest-handler — kortsluiten, loggen, authenticeren of excepties hermappen zonder subclassing.
OpenAPIOptions.Endpoint.BasePath plaatst een prefix vóór elke route en vóór de ingebouwde /openapi.json- & /docs-endpoints, zodat de API achter /api/v1 of een willekeurige namespace kan leven.
sgcRequired, sgcMinLength, sgcMaxLength, sgcRange en sgcPattern genereren de overeenkomstige schema-constraints, zodat dezelfde regels in de gegenereerde spec verschijnen en tijdens runtime worden afgedwongen.
Gezaghebbende bronnen voor de protocollen en formaten die dit component implementeert.
Spring direct naar de componentreferentie, pak de kant-en-klare demoprojecten en download de proefversie.
| Online-hulp — OpenAPI-server Volledige property-, methode- en eventreferentie voor dit component. | Openen | |
| Demoprojecten — Demos\23.OpenAPI Twee kant-en-klare voorbeelden: spec-first (Petstore JSON) en code-first (task manager). Meegeleverd in het sgcWebSockets-pakket — download hieronder de proefversie. | Openen | |
| Gebruikershandleiding (PDF) Uitgebreide handleiding die elk component in de bibliotheek behandelt. | Openen |