XData Swagger missing XML comments in code

[Henrik_Haumann]

I'm new to XData and to use the built-in swagger.
Using Delphi XE11.0.

I have made a small XDataserver following Holgers YT, the server runs and returns data as expected.

I have two issues.

I have enabled swagger and that works fine, except from XML comments added on the methods which are not shown in swagger - do I need to enable something else?
I've added " TXDataModelBuilder.LoadXmlDoc(XDataServer.Model);" to the datamodule oncreate where the XDataserver lives.

The result JSON data presented in swagger and in my browsers is not presented "nicely" it's just a bunch of data, are there a setting for getting the JSON result formatted nicely in swagger?
If I copy the data to notepad+ I can get the data formated using a JSON plugin so the result is valid JSON data.

regards
Henrik

[Henrik_Haumann]

Fixed issue 1 with xml documentation - never used that before so I didn't know you need to enable xml generation and set where to put the xml documents under compile.

[wlandgraf (Wagner Landgraf)]

Glad you solved the first issue. About the second "issue", that's by design., The swagger.json is intended to be read by machines (actually, most JSON documents are intended to do so), thus it's not formatted and compact for that reason. Indeed, if you want to read it in an editor, just use the editor features to make it readable.

[AndrewSimard]

I was also interested in issue 2. I did some searching and it seems that this is an option in Swagger UI. But I have no idea where, in a TMS XData project, these kinds of options can be set? The page that is generated (View Source when looking at the Swagger page) has a list of options defined like this:

<script>                                                                                               
  window.onload = function() {                            
  var url = "http://localhost:10415/Core/openapi/swagger.json"                                     
  var swaggerOptions = {                                
    url: url,                                           
    displayOperationId: false,         
    docExpansion: "none",                        
    filter: true,                                   
    dom_id: "#swagger-ui",                              
    deepLinking: true,                                  
    showExtensions: true,                               
    showCommonExtensions: true,                         
    presets: [                                          
      SwaggerUIBundle.presets.apis                      
    ]                                                   
  }                                                     
  var ui = SwaggerUIBundle(swaggerOptions)              
                                                        
  window.ui = ui                                        
}                                                                                                                                                   
</script>  

But I don't see where this can be altered? For example, I wouldn't mind if tryItOutEnabled was set to true by default. Regarding the prettyprint option, apparently, it can be set via

    <init-param>
      <param-name>swagger.pretty.print</param-name>
      <param-value>true</param-value>
    </init-param>

But similarly, I have no idea where this would need to be added?

[Henrik_Haumann]

Basically I think the problem is that the response content type is not set correct although it shows it in the swagger UI.

[Henrik_Haumann]

This could also be the "thing"

[Henrik_Haumann]

Reference is Holger's YT

TMS XData: Accessing any database with SQL queries via the TMS XData REST server

21.40 you'll see the nicely formated json result in the browser, which I also don't receive nicely from the dataset, however it works fine when showing /$model - which concludes that browser reads json perfectly and formats it nicely - and so should swagger.

[wlandgraf (Wagner Landgraf)]

Now I see what you mean, I misunderstood your initial question #2.

But well, I don't see such issue here, do you have steps to reproduce the issue? Can you share your project? It looks like the server is not including the content-type: application/json HTTP header. You can check it in the network tab of the browser request.

But steps or a project to reproduce the issue will help.

[Henrik_Haumann]

I have also mailed this project

Just connect to som sql table and request getalarms using swagger

ADXServer.zip (103.9 KB)

[Henrik_Haumann]

Well that's correct, response is not returned as requested, that's a XData issue isn't it?

[wlandgraf (Wagner Landgraf)]

Your GetAlarms method returns a TStream:

    function GetAlarms(includeOOS : boolean): TStream;

In this case, XData doesn't assume any content-type, since this is a low-level way of returning data. When you return a stream, you should set the content-type yourself:

function TAlarmDirectorService.GetAlarms(includeOOS: boolean): TStream;
var
  LResult : TStringStream;
begin
  // Add the following line
  TXDataOperationContext.Current.Response.Headers.SetValue('content-type', 'application/json');
  LResult := TStringStream.Create;
  uDBContainer.DataModule1.GetAlarmsBatch(includeOOS, LResult);
  Result := LResult;
end;

[AndrewSimard]

That works great! Any ideas on how to set those other Swagger parameters? Or is this something that could be added alongside the existing properties? I'm thinking specifically about tryItOutEnabled but there may be others as well.

[Henrik_Haumann]

Yes that is true, it returns a TStream, and this example is based on a YouTube video from you guys (Holger Flix) where he presents this approach - I found it to be a great way and started replicating to get more acquainted with XData and to investigate if I'd use your components as base in our future platform.

In this YT Holger doesn't show or mention that line, nor that it is considered "low level" ;) I for sure don't consider it LL.

TXDataOperationContext.Current.Response.Headers.SetValue('content-type', 'application/json');

It works, thanks

[wlandgraf (Wagner Landgraf)]

@AndrewSimard

That works great! Any ideas on how to set those other Swagger parameters? Or is this something that could be added alongside the existing properties? I'm thinking specifically about tryItOutEnabled but there may be others as well.

Good suggestion, we have implemented both TryItOutEnabled property and CustomParams (low level raw params for full flexibility). Some screenshots below, it will be included in next release.
For further comments on this subject I suggest starting a new topic.