swagger help needed

[David Schwartz 426]

Just FYI, I'm not "still on" any particular version of swagger. The project I _was_ on had swagger info published that's generated from Microsoft tools that are in widespread use, and that code itself reports that it was V2.0. 

 

I have sampled a bunch of swagger specs I've found around the internet, and I've found very few that are V3.0.

 

I don't know who produces these or how, but if most are being generated by MS tools, then consider it's MS themselves that's responsible for this disparity. Certainly nothing I'm connected to.

 

(I'm not on that project any more, and anyway they had told me not to even use Delphi. So at this point it's just a curiosity.)

 

If MS isn't supporting V3.0, then I'm not sure who's going to use it if it's really that hard to parse.

[Lars Fosdal 1792]

Swagger (2.0) had a name transplant and is now known as OpenAPI (3.0).

Quote

The good news for those that are familiar with Swagger 2.0 is that the changes made for OpenAPI 3.0 are backwards compatible in a functional sense, although your JSON or YAML file will need to be updated as the format has changed a little.

And... I now have literally hundreds of Swagger 2.0 APIs to translate to Delphi...

Any news from you guys on Delphi and Swagger libs?

 

Edit: Oh, btw - there is code in source\data\EMS.ResourceTypes.pas (D11.1) that generates rudimentary Swagger 2.0 specs in Json or YAML, but it contains numerous TO-DO comments.  I guess the author never got to do them, and there doesn't seem to be anything to read Swagger or YAML. 

 

[Wagner Landgraf 43]

12 hours ago, Lars Fosdal said:

And... I now have literally hundreds of Swagger 2.0 APIs to translate to Delphi...

By "translating" are you referring to importing and generating client for it?

If yes, I have provided a tool for that:

 

https://github.com/landgraf-dev/openapi-delphi-generator

[Wagner Landgraf 43]

2 minutes ago, Wagner Landgraf said:

By "translating" are you referring to importing and generating client for it?

If yes, I have provided a tool for that:

 

https://github.com/landgraf-dev/openapi-delphi-generator

Well, I see now that this is the original request of this topic. 😅

So there you go folks, hope it's useful. It works with Swagger v2 and OpenAPI 3.0.x specifications.

[David Schwartz 426]

8 hours ago, Wagner Landgraf said:

Well, I see now that this is the original request of this topic. 😅

So there you go folks, hope it's useful. It works with Swagger v2 and OpenAPI 3.0.x specifications.

hehe, yeah, 3 years later! 🙂 

 

I noticed that when it was released and thought ... where were you back when I need this? 🙂

 

[mvanrijnen 123]

I never got time to make our own generator public

. I am on holiday now. But try this out as soon as I get back 

[Dave Nottage 557]

If you're after something that does both (generate the doc, and parse it), there's this:

 

https://github.com/paolo-rossi/OpenAPI-Delphi

[Lars Fosdal 1792]

That looks very promising, @Wagner Landgraf!

 

I already have the code I need for pulling live specs and accessing the APIs.

How deeply tied are the TMS Biz classes?

 

Is the loaded Swagger/OpenAPI document class suitable for "plugging in" a custom class generator?

I already have a set of framework classes that I want to create code for.

[Wagner Landgraf 43]

1 hour ago, Lars Fosdal said:

How deeply tied are the TMS Biz classes?

It's only used to compile the generator executable. Anyone can compile, teste and contribute to code with the trial version.

The compiled executable is provided so you don't need TMS BIZ to use it.

The generated client code doesn't require TMS BIZ and works in both Delphi (XE8 and up) and Lazarus.

 

About the custom generator, there are events in the code that you can use to intercept and modify the code generation.

The OpenAPI parser can also be used separately, of course.

[Lars Fosdal 1792]

9 minutes ago, Wagner Landgraf said:

The OpenAPI parser can also be used separately, of course.

Quote

  OpenAPI.Classes,

  OpenAPI.Classes.Path,

  OpenAPI.Classes.Operation,

  OpenAPI.Classes.Parameter,

  OpenApi.Document,

  OpenAPI.Types,

Is that built on TMS Biz?

[Wagner Landgraf 43]

On 1/24/2023 at 6:05 AM, Lars Fosdal said:

Is that built on TMS Biz?

Yes.

[Arnaud Bouchez 407]

Just to inform anyone looking for an OpenAPI client code generator, that I just made a new one, for both Delphi and FPC.

It seems to be more advanced than Wagner's generator (e.g. it converts errors, enums and allOf/oneOf attributes), and is fully Open Source.

https://blog.synopse.info/?post/2024/09/06/Swagger/OpenAPI-Client-Generator-for-Delphi-and-FPC

 

Here are the top features of this OpenAPI client code generator for Delphi and FPC:

• 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
• Each method execution is thread-safe and blocking, for safety
• 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)
• Leverage the mORMot RTTI and JSON kernel for its internal plumbing
• Compatible with FPC and oldest Delphi (7-2009)
• Tested with several Swagger 2 and OpenAPI 3 reference content, but your input is welcome, because it is not fully compliant!

Hoping you may find it interesting.

The blog article has several example of the actual output of the generator, from several sources.
It is the kind of information I would have wanted to see with other libraries. Use the source, Luke!

 

Edited September 6 by Arnaud Bouchez

[David Schwartz 426]

On 9/6/2024 at 10:57 AM, Arnaud Bouchez said:

Just to inform anyone looking for an OpenAPI client code generator, that I just made a new one, for both Delphi and FPC.

It seems to be more advanced than Wagner's generator (e.g. it converts errors, enums and allOf/oneOf attributes), and is fully Open Source.

https://blog.synopse.info/?post/2024/09/06/Swagger/OpenAPI-Client-Generator-for-Delphi-and-FPC

 

This looks great, although it's 4 years after I created this thread and I am long gone from that employer. 

 

The article says a command-line version is "coming soon". Generally that would be sufficient for my typical needs. Is there any way to get updates on its progress?

Edited September 9 by David Schwartz

[Arnaud Bouchez 407]

@David Schwartz

Command line tool is now available:
https://github.com/synopse/mORMot2/tree/master/src/tools/mopenapi

(this is a good showcase how cross-platform and cross-compiler command line switches parsing could be done with mORMot)

I will release a Win32 binary somewhere in the next days.

 

Thanks for the feedback!