Line breaks in Swagger comments?

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

///

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:

1 Like

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 :slight_smile: Many thanks

1 Like

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;

1 Like

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.