0

We are using azure APIM and the Associated developer portal.

I would really like to display meaningful, well formatted documentation to our users in the dev portal, however Im struggling to find any good information or examples on how to do this.

We have code comments against our endpoints which are being output but the styling is not consistent with what I would expect, for example, normally XML comments such as this

    /// <summary>
    /// This is a summary of the endpoint
    /// </summary>
    /// <remarks>
    /// <para>This is paragraph one</para>
    /// <para>This is paragraph two</para>
    /// <remarks>

Should result in the remarks section containing two paragraphs, what we end up with is the the (obviously unrecognised and un-parsed) XML nodes <para> being rendered out so we get:

This is a summary of the endpoint
This is paragraph one This is paragraph two

At the moment I have been using trial and error because I cant find any specific documentation on this, I have been using this Recommended Tags for C# as a reference, but it doesn't seem to translate well into APIM dev portal.

I'd like to be able to add code samples, formatted text (Nothing fancy.. line breaks would be a start)

Any guidance would be appreciated because realistically we are stuck with APIM Dev Portal so I'm going to have to work something out.

Ideally I'd also like these comments to be referenced from a separate file because we try to keep our API controllers lightweight and at the moment one of them is 200 lines long and 150 of those are comments! - But that is something I can worry about another day!

Ecstasy
  • 1,866
  • 1
  • 9
  • 17
5NRF
  • 401
  • 3
  • 12
  • You can refer to [How to add a line break in C# .NET documentation](https://stackoverflow.com/questions/7279108/how-to-add-a-line-break-in-c-sharp-net-documentation), [XML multiline comments in C# - what am I doing wrong?](https://stackoverflow.com/questions/2547327/xml-multiline-comments-in-c-sharp-what-am-i-doing-wrong) and [xml comments - how to insert a new line](https://social.msdn.microsoft.com/Forums/en-US/5dce48f5-d810-46bd-bb9b-6d0478174cf2/xml-comments-how-to-insert-a-new-line?forum=csharpide) – Ecstasy Dec 24 '21 at 05:12
  • Ive tweeted support looking for guidance on what is and isnt supported. Its frustrating that conventions that are 10+ years old which work in swagger dont seem to work in the developer portal. – 5NRF Dec 24 '21 at 11:11

1 Answers1

0

For future reference this is what I have found when experimenting with the comments - a bit different from what I experienced in the original question (Guess I must have messed something up).

enter image description here

5NRF
  • 401
  • 3
  • 12
  • I also found that apim dev portal supports limited markdown syntax (Though I cant find any docs on that) – 5NRF Jan 04 '22 at 23:15