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.