Hi,
how can I put linebreaks in my xml comments so they will appear in the SwaggerUI?
none of the following is working...
///
/// line1
/// line2
///
///
/// line1
/// line2
///
///
/// line1
/// line2 <p/ara>
///
///
/// line1
/// line2
///
Hi,
how can I put linebreaks in my xml comments so they will appear in the SwaggerUI?
none of the following is working...
///
///
///
///
You can try adding <br />
as html embedded directly in the text? Also, if you start lines with hyphens, it creates bulleted lists for you. I think also if you have /// as a blank line between separate lines it might work?
/// line1
///
/// line2
For example, I've got this as part of the definition of a service endpoint:
/// <remarks>
/// Returns a JWT that includes a number of claims incorporated into it if successful.
///
/// Depending on the project/database, the authentication check may be as simple as a
/// lookup in a table, where the username and password are stored as SHA256 hashes.
/// In other cases, it may trigger an actual proper database authentication check.
///
/// JWT claims include the following.
///
/// - (iss) Issuer (String)
/// - (prj) Project (String)
/// - (dbn) Database Name (String)
/// - (dbc) Database Connection (String)
/// - (usr) Username (String)
/// - (net) IP Address (String)
/// - (iat) Issued (Timestamp)
/// - (exp) Expires (Timestamp)
///
/// NOTE 1: The issued/expires timestamps are based on the server's time.
///
/// NOTE 2: The JWT includes the prefix 'Bearer' to make it easier to copy/paste
/// the token into this SwaggerUI documentation. It is not part of the actual JWT.
///
/// NOTE 3: JWTs by default are issued for 60 minutes. Use LoginExtend to renew
/// a valid JWT for an additional 60 minutes.
/// </remarks>
And the Swagger web page is formatted like this:
Yes that works perfectly with the remarks tag.
My error was to use the summary tag. That one probably is not supposed to take line breaks Many thanks
Hmmm. Not sure the summary supports line breaks, as you say. I also recall setting the description that appears at the top of the page. I used this, seems to work, not sure if that helps or if there's a better way.
procedure TServerContainer.DataModuleCreate(Sender: TObject);
begin
// This enables Swagger documentation generation
TXDataModelBuilder.LoadXMLDoc(XDataServer.Model);
XDataServer.Model.Title := '500 Foods Oasis API';
XDataServer.Model.Version := '1.0';
XDataServer.Model.Description :=
'### Overview'#13#10 +
'This is an API for accessing systems that have implemented Oasis, a database'#13#10 +
'framework developed by 500 Foods Corporation for use in commercial greenhouses.'#13#10#13#10 +
'This framework can be found within many projects, including the following:'#13#10 +
'- EverydayIPM Pest Management App at [Dynamic Ecosystems Crop Protection](https://www.dynamicecosystems.ca)'#13#10 +
'- GLM Labour Management System at [Village Farms](https://www.villagefarms.com)'#13#10 +
'- Oasis Labour Management System at [Pure SunFarms](https://www.puresunfarms.com)'#13#10 +
'- Many other past and current projects'#13#10#13#10 +
'Please visit [500 Foods Corporation](https://www.500foods.com) for contact information.';
end;
There is also a demo in <xdata-install-dir>\demos\Swagger
folder that illustrates Swagger usage in many different modes and situations. It also shows line breaks there.