Adding documentation to Swagger Endpoints

Rohit_Nz · November 11, 2025, 6:18am

I started adding some documentation to Endpoints for Swagger. They appear fine on my local PC, but not on the server.

I have copied all xml files (against my better judgement), because most of them are not relevant and reveal too much about the code.

Is there some other file I have to copy?

The unit is Srv.Aux.pas Here is the Srv.Aux.xml.

The documentaion was added to

Request_Mobile_Registration
Login_Token_For_Mobile

<?xml version="1.0" encoding="utf-8"?>
<namespace name="Srv.Aux" platform="Win32">
  <interface name="IAux" GUID="{60359B60-C9D1-485D-A93D-8413B3FF76CC}" ancestor="IInvokable" file="Srv.Aux.pas" line="11">
    <attributes>
      <attribute name="TObject" />
    </attributes>
    <function name="Information" visibility="public" procflags="abstract virtual" file="Srv.Aux.pas" line="15">
      <attributes>
        <attribute name="TObject" />
      </attributes>
      <parameters>
        <retval type="TInformation" />
      </parameters>
    </function>
    <function name="Test" visibility="public" procflags="abstract virtual" file="Srv.Aux.pas" line="18">
      <attributes>
        <attribute name="TObject" />
      </attributes>
      <parameters>
        <retval type="string" />
      </parameters>
    </function>
    <procedure name="Update_Status" visibility="public" procflags="abstract virtual" file="Srv.Aux.pas" line="21">
      <attributes>
        <attribute name="TObject" />
      </attributes>
      <parameters>
        <parameter name="AEntity" type="TEntity" paramflags="const" />
        <parameter name="ARef" type="Int64" paramflags="const" />
        <parameter name="AStatus" type="Char" paramflags="const" />
      </parameters>
    </procedure>
    <function name="Request_Mobile_Registration" visibility="public" procflags="abstract virtual" file="Srv.Aux.pas" line="35">
      <attributes>
        <attribute name="TObject" />
      </attributes>
      <devnotes>
         <summary>
           Register a Mobile or Tablet
         </summary>
         <remarks> Returns &quot;Regn_Key&quot; to be saved to local storage </remarks>
         <param name="Device_Name"> Unique, save in local storage </param>
         <param name="Device_Type"> D,P,T = Desktop, Phone, Tablet </param>
         <param name="Email"> Email with company domain (Not checked yet) </param>
         <param name="Secret"> Secret obtained from the WebApp </param>
      </devnotes>
      <parameters>
        <parameter name="Device_Name" type="string" paramflags="const" />
        <parameter name="Device_Type" type="string" paramflags="const" />
        <parameter name="Email" type="string" paramflags="const" />
        <parameter name="Secret" type="string" paramflags="const" />
        <retval type="TString_Block" />
      </parameters>
    </function>
    <function name="Session_If_Regn_Is_Valid" visibility="public" procflags="abstract virtual" file="Srv.Aux.pas" line="42">
      <attributes>
        <attribute name="TObject" />
      </attributes>
      <parameters>
        <parameter name="Reg" type="string" paramflags="const" />
        <parameter name="Brws" type="string" paramflags="const" />
        <parameter name="Plat" type="string" paramflags="const" />
        <retval type="string" />
      </parameters>
    </function>
    <function name="Get_Fingerprint_And_Session" visibility="public" procflags="abstract virtual" file="Srv.Aux.pas" line="46">
      <attributes>
        <attribute name="TObject" />
      </attributes>
      <parameters>
        <parameter name="Dev_Name" type="string" paramflags="const" />
        <retval type="string" />
      </parameters>
    </function>
    <function name="Login_Token_For_Mobile" visibility="public" procflags="abstract virtual" file="Srv.Aux.pas" line="58">
      <attributes>
        <attribute name="TObject" />
      </attributes>
      <devnotes>
         <summary>
           Login from Mobile or Tablet App
         </summary>
         <remarks> Returns &quot;Token&quot; to be used for further communication </remarks>
         <param name="Device_Name"> From local storage </param>
         <param name="Regn_Key"> Registration Key From local storage </param>
         <param name="User_Name"> Using Email for now </param>
         <param name="Password"> To authenticate the user </param>
      </devnotes>
      <parameters>
        <parameter name="Device_Name" type="string" paramflags="const" />
        <parameter name="Regn_Key" type="string" paramflags="const" />
        <parameter name="User_Name" type="string" paramflags="const" />
        <parameter name="Password" type="string" paramflags="const" />
        <retval type="TLogin_Block" />
      </parameters>
    </function>
    <function name="Login_Token" visibility="public" procflags="abstract virtual" file="Srv.Aux.pas" line="65">
      <attributes>
        <attribute name="TObject" />
      </attributes>
      <parameters>
        <parameter name="User_Name" type="string" paramflags="const" />
        <parameter name="Password" type="string" paramflags="const" />
        <retval type="TLogin_Block" />
      </parameters>
    </function>
    <function name="Change_Password" visibility="public" procflags="abstract virtual" file="Srv.Aux.pas" line="70">
      <attributes>
        <attribute name="TObject" />
      </attributes>
      <parameters>
        <parameter name="Ref" type="Int64" paramflags="const" />
        <parameter name="Cur_Pwd" type="string" paramflags="const" />
        <parameter name="New_Pwd" type="string" paramflags="const" />
        <parameter name="Session" type="string" paramflags="const" />
        <retval type="TResult_Block" />
      </parameters>
    </function>
    <function name="User_Rights" visibility="public" procflags="abstract virtual" file="Srv.Aux.pas" line="77">
      <attributes>
        <attribute name="TObject" />
      </attributes>
      <parameters>
        <parameter name="User" type="string" paramflags="const" />
        <parameter name="Pwd" type="string" paramflags="const" />
        <retval type="Int64" />
      </parameters>
    </function>
    <function name="Client_Exists" visibility="public" procflags="abstract virtual" file="Srv.Aux.pas" line="82">
      <attributes>
        <attribute name="TObject" />
      </attributes>
      <parameters>
        <parameter name="AFirst" type="string" paramflags="const" />
        <parameter name="ALast" type="string" paramflags="const" />
        <parameter name="ANumber" type="string" paramflags="const" />
        <parameter name="AEmail" type="string" paramflags="const" />
        <retval type="Int64" />
      </parameters>
    </function>
    <function name="Booking_Type" visibility="public" procflags="abstract virtual" file="Srv.Aux.pas" line="89">
      <attributes>
        <attribute name="TObject" />
      </attributes>
      <parameters>
        <parameter name="Ref" type="Int64" paramflags="const" />
        <retval type="Integer" />
      </parameters>
    </function>
    <function name="Booking_Details" visibility="public" procflags="abstract virtual" file="Srv.Aux.pas" line="93">
      <attributes>
        <attribute name="TObject" />
      </attributes>
      <parameters>
        <parameter name="AAgency_Ref" type="Int64" paramflags="const" />
        <parameter name="AClient_Ref" type="Int64" paramflags="const" />
        <parameter name="APilot_Ref" type="Int64" paramflags="const" />
        <parameter name="AFueller_Ref" type="Int64" paramflags="const" />
        <parameter name="ABombardier_Ref" type="Int64" paramflags="const" />
        <parameter name="AShooter_Ref" type="Int64" paramflags="const" />
        <parameter name="ABaiter_Ref" type="Int64" paramflags="const" />
        <parameter name="ANavigator_Ref" type="Int64" paramflags="const" />
        <parameter name="ASpare1_Ref" type="Int64" paramflags="const" />
        <parameter name="ASpare2_Ref" type="Int64" paramflags="const" />
        <parameter name="ACraft_Ref" type="Int64" paramflags="const" />
        <retval type="string" />
      </parameters>
    </function>
    <function name="Add_To_Planner" visibility="public" procflags="abstract virtual" file="Srv.Aux.pas" line="107">
      <attributes>
        <attribute name="TObject" />
      </attributes>
      <parameters>
        <parameter name="ABooking_Ref" type="Int64" paramflags="const" />
        <parameter name="ACreated_By" type="Int64" paramflags="const" />
        <retval type="TPlan_Added" />
      </parameters>
    </function>
    <function name="EchoString" visibility="public" procflags="abstract virtual" file="Srv.Aux.pas" line="112">
      <parameters>
        <parameter name="AValue" type="string" paramflags="const" />
        <retval type="string" />
      </parameters>
    </function>
  </interface>
</namespace>

Weetch_Russell · November 11, 2025, 11:07am

I actually write the xml to a specific folder under the server output folder. In Project\Options\OtherOptions

Set Generate XML Documentation = True
Set XML Documentation Output Directory to where you want the XML to go

In my server datamodule.OnCreate

add
TXDataModelBuilder.LoadXmlDoc(ApiServer.Model, PathToXML);

Think that's about it. I do set the

TXDataServer.Model.Title
TXDataServer.Model.Version
TXDataServer.Model.Description

The last one I load from a resource

Rohit_Nz · November 11, 2025, 1:49pm

I looked at the source, If the path is not specified, it uses the executable path. Which is where I had put the xmls.

And they work on my pc, but not on the production server.

I tried a folder ".\xml" but now it doesn't work on my local PC either. Obviously, the xml files are there.

On both places, I can see in the browser that its loading the virtual swagger.json with a result of 200. I assume that where the doc ends up.

Do you put all the xml files on the server?

It works (in both places), when I put an absolute path for xml

Weetch_Russell · November 11, 2025, 2:09pm

Yes, I copy all the xml to the server

wlandgraf · November 11, 2025, 7:39pm

In any Delphi application, you should only use relative paths if you know the current directory you are working on. Do you?

Rohit_Nz · November 12, 2025, 12:09am

I do, and I never change it, but other libraries can. I am using LPath := ExtractFilePath(ParamStr(0)) + Xml_Path;, so its not super hard coded in the application.

Questions

Is there a way to target returns in the doc? I tried the <returns> tag but that didn't work, so I have put that in <remarks>.
Is there a way to turn off XML doc generation on a unit basis? I am just not happy having a list of all methods of every unit up on the production server.

wlandgraf · November 12, 2025, 11:09am

No.

Not that I know. But you can deploy just the XML you want, not all of them.

system · November 25, 2025, 12:50am

This topic was automatically closed 24 hours after the last reply. New replies are no longer allowed.

Topic		Replies	Views
XDATA + SwaggerUI+Onlinedocumentation TMS XData	7	505	October 29, 2021
XData Swagger missing XML comments in code TMS XData	14	1115	May 17, 2022
Problems with Xdata / Sparkle /Aurelious Server TMS XData	22	220	February 4, 2025
XData with Sphinx authorization TMS XData	18	202	July 1, 2025
Linux deployment not showing swagger required elements in JSON TMS XData	6	280	September 26, 2023

Adding documentation to Swagger Endpoints

Related topics