ANN: New Swagger/OpenAPI Client Generator for Delphi

[Arnaud Bouchez 407]

Since it seems to be a trending subject, a new OpenAPI client generator is now available for Delphi:
https://blog.synopse.info/?post/2024/09/06/Swagger/OpenAPI-Client-Generator-for-Delphi-and-FPC
 ;D

 

Here are some features of our OpenAPI code generator for Delphi and FPC:
- Fully OpenSource, both generator and generated source code
- Use high-level pascal records and dynamic arrays for "object" DTOs
- Use high-level pascal enumerations and sets for "enum" values
- Translate HTTP status error codes into high-level pascal Exceptions
- Recognize similar "properties" or "enum" to reuse the same pascal type
- Support of nested "$ref" for objects, parameters or types
- Support "allOf" attribute, with proper properties inheritance/overloading
- Support "oneOf" attribute, for strings or alternate record types
- Support of "in":"header" and "in":"cookie" parameter attributes
- Fallback to variant pascal type for "oneOf" or "anyOf" JSON values
- Generated source code units are very small and easy to use, read and debug
- Can generate very detailed comment documentation in the unit source code
- Tunable engine, with plenty of generation options (e.g. about verbosity)
- Tested with several Swagger 2 and OpenAPI 3 reference content
But still not fully compliant to all existing files: feedback is welcome!

 

Here is a snippet of a generated method signature, with high-level Data Transfer Objects as records (TUserShort/TDBAccount), and complete documentation, with proper Exceptions generation for the HTTP results error codes:

    // post_account_res_add_grant_auth [post] /accounts/{uuid}/add-grant-auth/
    //
    // Summary: Gives a user permissions to grant authorization on the account
    // Description:
    //   Roles: vm_admin for vm object, templates otherwise
    //
    // Params:
    // - [path] Uuid (required): Hypervisor uuid
    // - [body] Payload  (required)
    //
    // Responses:
    // - 200 (main): Success
    // - 400 [EValidationErrorResponse]: Parameters have invalid format or type
    // - 401 [EUnauthorizedResponse]: User is not authenticated
    // - 403 [EForbiddenResponse]: User has insufficient permissions
    // - 404 [EResourceNotFoundError]: Hypervisor not found
    // - 422 [EIntegrityErrorResponse]: Parameters have valid format but are not compatible
    // with the server state
    function PostAccountResAddGrantAuth(const Uuid: string; const Payload: TUserShort): TDbAccount;

The generated code is compatible even with oldest Delphi (7-2009) - nice to add native REST/HTTP client abilities to an existing monolithic application.
It is even fully compatible with FPC, because we should not be tied to a single compiler.

 

The source code of the generator is a single unit which leverages the mORMot RTTI and JSON kernel for its internal plumbing.

And you will find several generated sample code units in the blog article, to make yourself your idea about the level of this little unit.

 

Feedback is welcome!

[Der schöne Günther 316]

39 minutes ago, Arnaud Bouchez said:

which leverages the mORMot RTTI and JSON kernel for its internal plumbing

Just for my understanding as I went through the blogpost: This is a code generator for the mORMot library, not the Delphi RTL, correct?

[Arnaud Bouchez 407]

Indeed.

You need some basic units of  mORMot for the client code, because it uses its HTTP, RTTI and JSON cross-platform and cross-compiler abilities.
But are not tied to use the other mORMot ORM or SOA features, which are uncoupled from this.
To use the client methods, you just use the generated class methods, as with regular Delphi code. No fancy mORMot usage for the end user: the rodent stays hidden in his hole.
 

You have plenty of output sample in the blog article.

For instance: https://gist.github.com/synopse/e0dacfcc870db67013de55e43276f07b

unit auth.api;

{$I mormot.defines.inc}

interface

{
  --------------------------------------------------------------------
  AUTHENTIQ API client as TAuthClient class
  Generated 6 Sep 2024 by ab via mormot2tests - DO NOT MODIFY BY HAND!
  --------------------------------------------------------------------
}

uses
  classes,
  sysutils,
  mormot.core.base,
  mormot.core.unicode,
  mormot.core.text,
  mormot.core.buffers,
  mormot.core.datetime,
  mormot.core.rtti,
  mormot.core.json,
  mormot.core.variants,
  mormot.net.client;

 

Edited September 7 by Arnaud Bouchez

[Arnaud Bouchez 407]

I have edited the blog post to make it clear:

Quote

Of course, you would need some basic mORMot units in your client code. The tool does not generate a "pure Delphi RTL" client. But to be fair, there was no JSON support in early Delphi, and maintaining the differences between versions of compilers and RTL, especially about JSON, RTTI, HTTP would end up in something as reinventing the mORMot. We just use what works.
Note that the generated client code does not depend at all of the other mORMot features, like ORM or SOA. It is perfectly uncoupled from those very powerful, but sometimes confusing features. With the client code, you will use the mORMot, without noticing it. The rodent will hide in its hole. But if you need it, e.g. for adding logs or services, it would be glad to help you. 🙂