RAD Studio 10.4.1 is now available! Learn more. Looking for discounts? Visit our Special Offers page!
News

Embedding Swagger UI into RAD Server

This post is an update to the original post written previously showing Swagger UI being used with RAD Server, covering new features of RAD Server.

Why Embed Swagger UI into RAD Server?

Swagger UI (as previously discussed) is a great option for checking your documentation and working with the REST API. One of the challenges has always been CORS (Cross Origin Resource Sharing) that makes execution of the code a challenge when developing.

There are a few options now however. You can either work around this with browser plug-ins, (as seen before), enable CORS in the emsserver.ini under [Server.APICrossDomain], or embed swagger-ui inside your RAD Server instance.

In this video, I cover the latter option. You can watch how to get documentation up and running. The video shows how to configure your EMSServer.ini to share the external resource through RAD Server and also modify the downloaded files to automatically load up the API documentation directly from RAD Server.

WebFiles in RAD Server EMSServer.ini

The key to making this work is the WebFiles option that was added to RAD Studio in 10.3.2. This was primarily added to make it easier to serve out web content and support ExtJS for doing web client development under the Architect edition of RAD Studio, however, this also has the benefit of making other content available to share.

To make a path available, you need to edit the emsserver.ini (default path C:\Users\Public\Documents\Embarcadero\EMS\emsserver.ini). From there you can then setup in the [Server.PublicPaths] any number of endpoints.

The end point is setup as a JSON structure that is the value of an arbitrary name. e.g.

Path3={"path": "swagger-ui", "directory": "Z:\\Source\\git\\swagger-ui\\dist\\", "default": "index.html", "extensions": ["css", "html", "js", "map", "png"], "charset": "utf-8"}

An example should be in place already for you to un-comment and also update the directory. My personal preference is a shared folder on my Macbook, which I then share to the Windows VM’s. It means I just have one place to keep it updated.

RAD Server Documentation Attributes

Jim McKeith has done a post on documenting RAD Server API’s that I would recommend looking at. In addition to his content, the video also explores defining ResourceSuffix with named parameters.

There are 3 key attributes covered. (In the example below, placed above the TEMSDataSetResource, to define the use of the resource for documentation)

[EndPointRequestSummary('Exams', 'Exams', 'List of Exam', 'application/json', '')]

[EndPointRequestParameter(TAPIDocParameter.TParameterIn.Path, 'EXAM_ID', 'EXAM_ID for identifying a specific exam', false, TAPIDoc.TPrimitiveType.spInteger, TAPIDoc.TPrimitiveFormat.None, TAPIDoc.TPrimitiveType.spInteger, '', '')]

[ResourceSuffix('./')]
[ResourceSuffix('List', './')]
[ResourceSuffix('Get', './{EXAM_ID}')]
[ResourceSuffix('Put', './{EXAM_ID}')]
[ResourceSuffix('Delete', './{EXAM_ID}')]
dsrEXAM: TEMSDataSetResource;

It is important to note, that the ResourceSuffix defines the base URL call. The List, Get, Put, Delete attributes, then define the  extension to that call (important when writing out master detail (covered in the second video and following blog post).

The ResourceSuffix resource delegation is very powerful, making this very quick to build.

The post Embedding Swagger UI into RAD Server appeared first on Stephen Ball’s Technical Blog.


Reduce development time and get to market faster with RAD Studio, Delphi, or C++Builder.
Design. Code. Compile. Deploy.
Start Free Trial   Learn More About Upgrading

Deep Dive Webinar: Boost C++Builder Compile Speed with TwineCompile
About author

Pre-sales Director at Embarcadero
Related posts
CodeDelphiRAD Studio

Learn About How To Redirect Inserting, Deleting And Updating Records In Delphi With FireDAC

CodeDelphiRAD Studio

Learn How To Send Arrays To A PostgreSQL Database Server Using FireDAC In Delphi On Windows

CodeDelphiRAD Studio

TFDBatchMove Is A Powerful Way To Move Data Between Text Files And Tables Using Datasets In Delphi

CodeDelphiRAD Studio

Learn How To Use FireDAC In The Dynamic-Link Libraries With DLL Sharing Sample In Delphi

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

IN THE ARTICLES