Show/Hide Toolbars

TMS XData Documentation

Navigation: Other Tasks

Using XML Documentation with Swagger

Scroll Prev Top Next More

A good (if not the best) way to document your source code is to use XML Documentation Comments. In the interfaces and methods that build your service contract, you can simply add specific XML tags and content, like this:

 

    /// <summary>
    ///   Retrieves the sine (sin) of an angle
    /// </summary>
    /// <remarks>
    ///  Returns the Sine (Sin) value of an angle radians value.
    ///  The value returned will be between -1 and 1.
    ///  If the angle is zero, the returned value will be zero.
    /// </remarks>
    /// <param name="Angle">
    ///   The angle in radians.
    /// </param>
    function Sin(Angle: Double): Double;

 

And Delphi IDE will automatically use it for Help Insight, showing you information about the method on-the-fly. For example, if some developer is trying to use the Sin method of your API, information will be conveniently displayed:

 

xdata-xml-help-insight

 

The good news is that, with XData, you can use such XML comments in the Swagger document and Swagger-UI that are generated automatically by XData, improving even more your REST API documentation. Since the API endpoints are generated directly from the interfaced and methods, XData knows exactly the meaning of each documentation and can map it accordingly to Swagger.

 

 

Enabling generation of XML documentation files

 

XData needs to read the XML files with the comments to import it into the Swagger document. You need to tell Delphi compiler to generate the XML documentation files.

 

In your project options (Delphi menu Project | Options, or Shift+Ctrl+F11), go to "Building, Delphi Compiler, Compiling" (for Delphi 10.4.1 Sydney. Previous Delphi version might differ), the enable option "Generate XML documentation". You might also want to explicitly set the directory where the XML files will be generated, in option "XML documentation output directory". It's recommended to use ".\$(Platform)\$(Config)", this way the XML files will be in the same folder as the executable.

 

xdata-xml-project-options

 

 

Importing XML documentation in Swagger

 

XML documentation usage in Swagger can be enabled with a single line of code:

 

uses {...}, XData.Aurelius.ModelBuilder;
 
...
 
  TXDataModelBuilder.LoadXmlDoc(XDataServer.Model);

 

Add the line at the beginning of your application, be it in your dpr file, or initialization section of some unit, or in the OnCreate event of your TDataModule that contains your XData/Sparkle components. In the first parameter you must provide the XData model you want to import XML files to. In the example above, XDataServer is a TXDataServer component. If you are using multi-model design, just provide the proper model there.

 

LoadXmlDoc will try to find the XML files in the same directory as your application is located. If the XML files are in a different folder, you can specify it explicitly using a second parameter:

 

TXDataModelBuilder.LoadXmlDoc(XDataServer.Model, 'C:\MyXMLFiles');

 

Once you do that, if you check your Swagger documentation via Swagger-UI, you will see something like this:

 

xdata-xml-swagger-example

 

Note how the content of summary tag goes directly at the right of the GET button, as a summary for the endpoint.

 

The content of remarks tag is the detailed description of the endpoint.

 

And the content of each param tag for explains each respective parameter. Sweet!

 

 

Using different documentation for Help Insight and Swagger

 

Reusing the same XML comments is nice as you don't repeate yourself. Document your code just once, and the same documentation is used for documenting your Delphi interfaces (Delphi developments) and your REST API (API consumer development).

 

But, if for some reason you want to use different documentation content for Delphi developers and for REST API users, that's also possible. You can use the specific swagger tag to fill specific parts of the documentation. You then use the name attribute to differentiate between swagger tags.

 

For example, suppose the following documentation:

 

xdata-xml-doc-source

 

 

Note that tags summary (1) and param (2 and 3) are the regular XML documentation tags. They will be used for Help Insight:

 

xdata-xml-help-insight-2

 

And swagger tags with no name attribute (A), or name param-A (B), param-B (C) and remarks (D) will be used exclusively for Swagger documentation:

 

xdata-xml-swagger-example-2

 

 

Customizing tags

 

You can also customize the tags in Swagger. Endpoints are grouped together inside a tag, which can have a name and description.

 

By default, the name of the tag will be path segment of the interface service. But you can change it using either swagger tag using tag-name attribute.

 

The description of the tag by default is empty, but you can define it using the regular summary tag, or optionally using the swagger tag with tag-description attribute.

 

Consider the following documentation for both IArithmenticService and ITrigonometryService:

 

xdata-xml-tag-source

 

The above tags will generate the following output in Swagger UI:

 

xdata-xml-swagger-tags

 

 

Customizing document header and description

 

XData also takes the model name, version and description into account to build the final document. You can configure such settings directly by changing some properties of the XData model (remember that XDataServer in this example is a TXDataServer component):

 

  XDataServer.Model.Title := 'Mathematics API';
  XDataServer.Model.Version := '1.0';
  XDataServer.Model.Description :=
    '### Overview'#13#10 +
    'This is an API for **mathematical** operations. '#13#10 +
    'Feel free to browse and execute several operations like *arithmetic* and *trigonometric* functions'#13#10#13#10 +
    '### More info'#13#10 +
    'Build with [TMS XData](https://www.tmssoftware.com/site/xdata.asp), from [TMS Software](https://www.tmssoftware.com).' +
    'A Delphi framework for building REST servers'#13#10 +
    '[![TMS Software](https://download.tmssoftware.com/business/tms-logo-small.png)](https://www.tmssoftware.com)';

 

Note that you can use Markdown syntax to format the final text. Here is what it will look like:

 

xdata-swagger-doc-description