XDATA + SwaggerUI+Onlinedocumentation

BIZ TMS XData
1

XDATA + SwaggerUI + online documentation

At which point on the Apache server must the XML files for the documentation of the REST functions be stored in the SwaggerUI interface. I have already tried the following places:

  • in the directory in which the Apache module (so-module) is located
  • in the root directory of the virtual server
  • in a directory which I have defined via TXDataModelBuilder.LoadXmlDoc (Result.XModel, /server/xml)

Is someone in an Apache environment using the XML files to document the REST functions?

Frank

2

The XML files must be explicitly load from your application. You have to call LoadXmlDoc, and since it allows you to provide the directory of XML files, easiest approach is just save it whenever you feel more comfortable with, and pass the directory to LoadXmlDoc for them to be loaded.

3

I tried to set the directory with TXDataModelBuilder.LoadXmlDoc (Result.XModel, /serverdirectory/xml), unfortunately without success. How can I check whether the XData server can access this directory.

The comments for Swagger are available in the generated XML files. Is there anything else that needs to be considered here?

4

What is the result? What do you see? What is the exact code you are using?

5

Here the code snippet

begin
RegisterOpenAPIService;
RegisterSwaggerUIService;
result.SwaggerOptions.AuthMode:=TSwaggerAuthMode.Jwt;
result.SwaggerUIOptions.ShowFilter:=TRUE;

TXDataModelBuilder.LoadXmlDoc(Result.XModel, const_HTTP_SERVER_DOCUMENTATION);

result.XModel.Title := 'e-vendo AG Rental API';
result.XModel.Version := const_API_VERSION;
result.XModel.Description :=
    '### Overview'#13#10 +
    'This is an API for **rental** operations. '#13#10 +
    'Feel free to browse and execute several operations like *rental* ';

end;

const: const_HTTP_SERVER_DOCUMENTATION = '/bikerental/documentation';

The application runs on a linux server.
SwaggerUI works perfectly. Apart from the title, the version and the description in the head of swagger, no documentation is shown when the function is called.

here is the documented text from the unit:
['{E3B42CF1-0E85-4445-AB26-610ED0BF91DE}']

/// <summary>
///  Anmeldung über APIKEY, Loginname und Passwort. APIKEY wird in der Datenbank gepflegt
///  als Ergebnis wird ein JWT-Token zurückgeliefert
/// </summary>
/// <param name="ApiKey">
///   ApiKey für den Zugriff per Loginname und Passwort.
/// </param>
/// <param name="User">
///   Benutzername aus der Adressverwaltung mit aktiviertem Internet-Account.
/// </param>
/// <param name="password">
///   Passwort des Benutzers
///  </param>
///
///  <swagger>
///  Erzeugung eines JW-Token für die Kommunikation mit der API
///  </swagger>
///  <swagger name="ApiKey">
///  ApiKey für den Zugriff auf diesen Mandanten
///  <swagger>
///  <swagger name="User">
///  Benutzername aus dem Internet-Account der Adresse oder des Ansprechpartners
///  </swagger>
///  <swagger name="Password">
///  Passwort aus dem Internet-Account der Adresse oder des Ansprechpaertners
///  </swagger>
///  <swagger name="remarks">
///
///  Über diese Funktion wird auch die Berechtigung ermittelt, mit der der Benutzer Modulaktionen ausführen kann
///
///  </swagger>
[HttpPost] function Login(ApiKey, User, Password, LanguageCode: String): String;
6

I guess you can simply add some debug code and check if there is any .xml file in the directory /bikerental/documentation, to isolate the problem a little bit more.

7

The XML files with the comments are in the / bikerental directory. Can I see in which directory swagger is looking to use the files for display?

How can I determine whether the specified directory can be used by swagger?
Can an error be detected if swagger cannot find these files in the configured directory?

8

I'm suggest you write Delphi code that reads the folder content and check for .xml files. Something like

Path.GetFiles(const_HTTP_SERVER_DOCUMENTATION + '*.xml')

And check if there are files there. XData will simply use a xml file if it's there, if it's not there is no "error".