sgcOpenAPI Quick Start

At a glance

There is no component to drop

This is the single thing to understand before you start. sgcOpenAPI registers nothing on the IDE palette, and it ships no design-time package. The workflow is generate, then use.

The tool

sgcOpenAPI.exe, which is both a GUI wizard and a command line. It reads a specification and writes one .pas file.

What it writes

A unit containing a client class descended from TsgcOpenAPI_Client, one method per operation, the request and response classes, and a GetOpenAPIClient function that returns a ready singleton.

How you call it

Add the generated unit to your project, put it in the uses clause, and call GetOpenAPIClient.YourOperation(...). The result is a response object you free when you are finished with it.

The packages

Five runtime packages ship, holding pre-built SDKs for AWS, Azure, Google and Microsoft. They are for compiling, not for installing, because there is no palette page to add.

Before you start

Requirements and editions

The edition column is the define that gates the code, with the line it sits on in the product's own Source/sgcVer.inc.

What	Value
IDE	Delphi 7 through RAD Studio 13 for the generated code. Typed response objects need XE7 or later, and the shipped demo guards them with `{$IF CompilerVersion >= 28.0}`. Below that the generated method returns a plain string.
C++Builder	Not supported for the generated client. `SGC_HTTP_OPENAPI`, which gates the whole of `sgcHTTP_OpenAPI_Client.pas`, is defined inside an `{$IFNDEF BCB}` on line 702 of the product's `sgcVer.inc`, so a C++Builder build compiles that unit to nothing.
Edition	sgcOpenAPI builds are pinned to the two lowest tiers. Lines 7 to 10 of its `sgcVer.inc` read `{$IFDEF SGC_OPENAPI}` followed by `{$UNDEF SGC_EDT_PRO}`, `{$UNDEF SGC_EDT_ENT}` and `{$UNDEF SGC_EDT_ALL}`, leaving Core and Standard defined. The commercial tiers are by seat count, not by feature.
Server generation	The same build defines `SGC_HTTP_OPENAPI_SERVER` on line 11, so the generator can emit a server stub as well as a client. Pass `-s` on the command line.
Platforms	No unit-scope operating system guard. The only conditionals inside the generated-client base unit are the usual `{$IFDEF MSWINDOWS}` import and thread-id type swaps, so Windows, macOS, Linux, Android and iOS all compile.
Licence activation	If the machine has not been activated, pass `-user` and `-password` to the command line, otherwise the run exits with code 2.

The generator accepts JSON and YAML, and reads both locally. A Swagger 2.0 document is converted to OpenAPI 3 locally as well. The remote converter is opt in, through -r, and it uploads your specification to a third party server, so it stays off unless you ask for it.

Step 1

Install and generate

There is no design-time package to install, so the install is shorter than for the other products.

1. Unzip

Unzip the download to a folder, called {$DIR} below. You get Demos\, Bin\ and Source\.

2. Library path

Tools, Options, Library. Add {$DIR}\Source so the generated units and the client base class resolve. There is nothing to install into the IDE.

3. Optional, compile a pre-built SDK

If you want one of the bundled SDKs, open the matching runtime package under {$DIR}\Packages\ and compile it. These are runtime packages, so compile rather than install.

4. Generate a client

Run Bin\sgcOpenAPI.exe for the wizard, or use the command line. One input, one output, and you have a unit.

5. Add the unit to your project

Put the generated .pas next to your other units, add it to the project and put it in your uses clause. That is the whole integration.

QuickStart

Specification in, working client out

One command line generates the unit. One call uses it. The third tab shows the switches worth knowing on the first day.

command line

> sgcOpenAPI.exe -i "geolocation.json" -o "geolocation.pas"

File successfully created geolocation.pas

Both switches are mandatory. -i takes a local file or a URL and accepts JSON and YAML, and -o is the Pascal unit to write. There is a GUI wizard in the same executable if you would rather click. Add the generated .pas to your project and it is ready to use.

fGeolocation.pas

uses
  geolocation;   // the unit you just generated

procedure TfrmGeolocation.btnGeolocationClick(Sender: TObject);
var
  oResponse: TsgcOpenAPI_Retrieve_the_location_of_an_IP_address_Response;
begin
  oResponse := GetOpenAPIClient.Retrieve_the_location_of_an_IP_address(
    txtAPIKey.Text, txtIPAddress.Text);
  try
    if oResponse.IsSuccessful then
      memoResponse.Lines.Text :=
        'country: ' + oResponse.Successful.Country + #13#10 +
        'city: ' + oResponse.Successful.City
    else
      memoResponse.Lines.Text := oResponse.ResponseError;
  finally
    oResponse.Free;
  end;
end;

GetOpenAPIClient is generated into the unit and takes no parameters. One method per operation, named from the operation id. The response object is yours to free, which is why the demo uses a try finally. On Delphi versions before XE7 the generated method returns a plain string instead, and the shipped demo guards the typed path with {$IF CompilerVersion >= 28.0}.

command line

-s              generate a server stub instead of a client
-a 3            add an OAuth2 flow to the generated client
                (0 none, 1 basic, 2 token, 3 oauth2, 4 jwt)
-u <url>        set the base url the generated client uses
-m 1            name methods from summary rather than operationid
                (0 operationid, 1 summary, 2 endpoint)
-x <list|file>  exclude operations, as "VERB endpoint"
-p              generate only the classes the kept operations use
-nc             do not create pascal classes
-l              show progress messages (errors are always shown)
-user -password activate the licence on this machine

On a large specification, -x and -p together are the difference between a unit you can open in the IDE and one you cannot. -r exists as well, and it is deliberately off by default because it uploads the whole specification to a third party converter.

The generate command is the usage line printed by the tool's own help. The call is the shipped demo Demos\20.Client\abstractapi.com\geolocation\fGeolocation.pas, with the form controls replaced by literals. That demo ships the specification and expects you to generate the unit, which is why the quick start starts with the generator.

Step 2

Check the generator succeeded

Two things to look at, and one of them is scriptable.

The message

The tool prints File successfully created followed by the output path. Errors always go to standard error, so a quiet run that wrote nothing is not silent.

The exit code

0 success, 1 error, 2 invalid licence, 3 invalid switch, 4 invalid config file, 5 invalid input file, 6 invalid output file, 7 the specification could not be converted to a valid OpenAPI 3 document. Test it in your build script.

The unit compiles

Add the generated .pas to the project and build. It should compile against nothing but {$DIR}\Source on the library path.

`IsSuccessful`

At runtime the response object tells you. When it is false, ResponseError carries the message and ResponseCode the HTTP status.

Common problems

What usually goes wrong the first time

Six problems account for nearly every first run.

You are looking for a component on the palette

There is not one. sgcOpenAPI registers no components and ships no design-time package. The generated unit is the integration point, and GetOpenAPIClient is how you reach the client.

The unit named in the demo does not exist

That is expected. The demos ship the specification and not the generated unit, so you run the generator first. The geolocation demo needs a unit called geolocation, which comes out of geolocation.json.

Exit code 2

The licence has not been activated on this machine. Pass -user and -password on the command line.

The typed response object will not compile

Typed responses need XE7 or later. The shipped demo guards them with {$IF CompilerVersion >= 28.0} and falls back to a method that returns a plain string on older compilers. Keep that guard if you support Delphi 7.

Nothing compiles under C++Builder

SGC_HTTP_OPENAPI is defined inside an {$IFNDEF BCB} on line 702 of the product's sgcVer.inc, so the generated client base class is not compiled for C++Builder at all.

The specification will not convert

Exit code 7 means the document could not be turned into a valid OpenAPI 3 document. YAML and Swagger 2.0 are handled locally; the remote converter behind -r is the escape hatch, and it uploads the whole file to a server eSeGeCe does not control.

Go deeper

Beyond the first client

Four directions, all from the same generator.

Generate a server, not a client

Pass -s and the generator emits a server stub instead. The server demos show how the emitted operations are dispatched and validated against the specification.

sgcOpenAPI Server

Use the pre-built SDKs

More than a thousand specifications are already generated and shipped, including AWS, Azure, Google and Microsoft. Compile the package you want and skip the generation step entirely.

The bundled APIs

Trim what you generate

-x excludes operations by verb and endpoint, and -p prunes the classes that no remaining operation uses. On a large specification this is the difference between a unit you can open and one you cannot.

The parser

Wire in authentication

The generated client carries an Authentication property, and -a chooses the scheme at generation time: none, basic, token, OAuth2 or JWT.

sgcOpenAPI features

Resources

Reference, demos and documentation

Demo projects ship inside the download, under Demos\: pre-built SDKs, a generated client and two server samples.

	What sgcOpenAPI does The parser, the generator and the server component in one page.	Open
	The parser How a specification is read, validated and turned into Pascal types.	Open
	The server component Serving an API from a specification rather than consuming one.	Open
	Bundled APIs The pre-built SDKs that ship ready to compile.	Open
	Download the trial The generator and the source, time limited.	Open
	What is OpenAPI Background, if the specification format itself is new to you.	Open

Related reading: generating a Delphi client from OpenAPI, bundling schemas, sgcOpenAPI compared with swagger-codegen and the OpenAPI server. Every product has its own quick start, listed on the getting started page.

FAQ

sgcOpenAPI quick start questions

None. sgcOpenAPI is a code generator and a runtime library, and it registers nothing on the IDE palette. There is no design-time package in the product at all. You run sgcOpenAPI.exe against a specification, it writes one Pascal unit, and you add that unit to your project. Inside it, GetOpenAPIClient returns a ready client object with one method per operation.

The tool prints it in its own help: sgcOpenAPI.exe -i "c:\openapi.json" -o "c:\openapi.pas". Both switches are mandatory. -i takes a local file or a URL, and JSON and YAML are both accepted. -o is the Pascal unit to write. A value can also be appended after a colon, as in -i:"c:\openapi.json".

Two ways. The tool prints File successfully created followed by the output path, and it sets an exit code you can test in a build script. The codes are 0 success, 1 error, 2 invalid licence, 3 invalid switch, 4 invalid config file, 5 invalid input file, 6 invalid output file, and 7 the specification could not be converted to a valid OpenAPI 3 document. Errors always go to standard error.

The generated method returns a response object descended from TsgcOpenAPIResponse. Read IsSuccessful first. When it is false, ResponseError carries the message and ResponseCode the HTTP status. Free the response object when you are finished with it, which the shipped demo does in a try finally.

The generated client does not. SGC_HTTP_OPENAPI, which wraps the entire interface of sgcHTTP_OpenAPI_Client.pas, is defined inside an {$IFNDEF BCB} on line 702 of the product's sgcVer.inc, so under C++Builder that unit compiles to nothing and the generated code has no base class. Generate for Delphi.

The generated code targets Delphi 7 and later. The typed response objects need XE7 or later, and the shipped demo makes that explicit with {$IF CompilerVersion >= 28.0}: above the line you get a response object with typed fields, below it the same method returns a plain string. Keep the guard if your project has to build on both.

Yes. Pass -s and the generator emits a server stub with code-first attributes instead of a client. The build that ships as sgcOpenAPI defines SGC_HTTP_OPENAPI_SERVER on line 11 of its sgcVer.inc, so the server side is present in every licence. Two server demos ship under Demos\30.Server.

Not unless you ask. YAML is read locally, and a Swagger 2.0 document is converted to OpenAPI 3 locally. The -r switch, which is off by default, allows a fallback to the public converter at converter.swagger.io, and the help text says plainly that this uploads the complete file to a server eSeGeCe does not control. Leave it off for anything confidential.

sgcOpenAPI in five minutes