Documenting your Delphi REST API the easy way
Create documentation is boring. At least that’s my opinion, and most developers I know also don’t like to write it. But that’s something we need to do, of course. Thus, the easiest it gets to document things, the better. Photo by Aaron Burden on Unsplash With TMS XData, you create your REST API server using Delphi very easily, but you also get it documented almost automatically using the automatic Swagger generation feature. Since all endpoints are strong typed in server, all it takes is just to enable a single property and have your endpoints listed and testable. This feature has been available for years already. But now XData takes it to another level. 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: /// /// Retrieves the sine (sin) of an angle /// /// /// 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. /// /// /// The angle in radians. /// 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: 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. By asking Delphi to generate the XML documentation files, and using a single line of code like this: uses {…}, XData.Aurelius.ModelBuilder; … TXDataModelBuilder.LoadXmlDoc(XDataServer.Model); XData will reuse the documentation and include it in Swagger: Using different documentation for Help Insight and Swagger Reusing the same XML comments is nice as you don’t repeat 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. For example, suppose the following documentation: Note that tags summary and param are the regular XML documentation tags. They will be used for Help Insight: 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: 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 : The above tags will generate the […]
