Markdown Monster
Approach for creating API documentation
Gravatar is a globally recognized avatar based on your email address. Approach for creating API documentation
  Keith Harvey
  Nov 1, 2022 @ 09:09am

I'm trying to find a good workflow for creating developer API documentation for my .NET libraries. I purchased Markdown Monster as one possible tool. I also see that you have an HTML Help tool.

I already have C# XML docs in my code for Intellisense, but want to offer more documentation than just what comes out of that.

Is there a way to export the C# XML docs into a markdown file that I can edit and add examples, images, etc.? It would be cool if Markdown Monster could extract out the C# XML docs into markdown.

I want to try to avoid duplicating my effort with the C# XML docs in the code, but I'm open to any ideas.

Gravatar is a globally recognized avatar based on your email address. re: Approach for creating API documentation
  Rick Strahl
  Keith Harvey
  Nov 1, 2022 @ 04:59pm

Markdown Monster isn't really meant as a documentation tool per se, although many people use it for that. It doesn't provide for the structure of a 'project' that provides the outline and linking of topics, so that's something that has to be managed separately anyway.

I've actually been working on a tool that sits ontop of Markdown Monster, but it's not anywhere near ready at this time - Swagger/OpenAPI imports will be part of the tool (as well as .NET documentation from XML docs and assembly meta data). Help Builder does the latter today, but it doesn't have support for swagger and HB is kind of getting long in the tooth being a pre-.NET application.

To throw even more confusion into this, my REST client/Web Load Testing tool - West Wind WebSurge - supports imports of Swagger APIs and I'm also in the process of creating support for documentation for API requests. From there printing documentation is a small step but this also in progress with no specific delivery date.

So for the moment I have no solution for you short of manually creating documentation. Personally what I do these days is use WebSurge to capture request traces and from that create API documentation by explicitly writing out the documentation using a simple template with data I get from standard Swagger/OpenAPI output. It's not automated but actually pretty straight forward.

Formatting and how to handle this is actually something I'm thinking about in Web Surge and debating on whether I should automatically pull in request/response formats, or simply allow plain text with custom formatting for the request traces.

+++ Rick ---

© 1996-2022