Layer7 API Management

Groups in our company are getting ready to expose a number of APIs through the API portal. One of the concerns they had was the effort required to populate, maintain, update API documentation for the number of APIs they are looking to expose.

Today we leverage the CMS user role and give users templates to fill in documentation (template is essentially just a document with html directives such as br, div, h1, h2 etc.) to help teams populate the content and then we essentially publish that in staging and then to prod.

The process of writing html document is difficult for some. Do you have any recommendation for any editor (perhaps some sort of WYSIWYG editor) that can make this process easier for folks who may not be as familiar with html?

Disclaimer: I personally haven't written any API documentation on the API portal. Just trying to address the concern I heard from some of the teams.

Anyone able to assist here?

Thank you

ash alam wrote:

 

Groups in our company are getting ready to expose a number of APIs through the API portal. One of the concerns they had was the effort required to populate, maintain, update API documentation for the number of APIs they are looking to expose.

 

Today we leverage the CMS user role and give users templates to fill in documentation (template is essentially just a document with html directives such as br, div, h1, h2 etc.) to help teams populate the content and then we essentially publish that in staging and then to prod.

 

The process of writing html document is difficult for some. Do you have any recommendation for any editor (perhaps some sort of WYSIWYG editor) that can make this process easier for folks who may not be as familiar with html?

 

Disclaimer: I personally haven't written any API documentation on the API portal. Just trying to address the concern I heard from some of the teams.

Hi AshAlam,

I apologize for the delay in responding.

Please correct me if I am wrong, but my current understanding of your post is that you are manually creating your API documentation with a lot of different people contributing, some well versed in HTML and others not so versed. Is that right? If so, then the best way to do this, in my opinion, is to use the built-in WYSIWYG editor when manually creating new documentation. And it can take a paste from a Word document as well with bullet points and such, so depending on how complex your documentation is design-wise, you may be better to have your colleagues generate documentation in Word and someone pastes it into the WYSIWYG editor when creating the new documentation page.

For what its worth, we tend to encourage the use of auto-generated documentation if at all possible as it generally can save a lot of time. If you are able to change the workflow to use auto-generated documentation, it may be very well worth it in time saved. Details for auto-generated documentation (which uses a WADL) is found in the API Developer Portal User Guide.

Please let me know if this answers your question or if there is anything else I can do to further assist you with this question. Thank you for your time, and my apologies again for the delay in responding.

Sincerely,

Dustin Dauncey

Support Engineer, CA Technologies

Email: API-Support@ca.com

Phone: +1 800 225 5224

Outside of North America - http://www.ca.com/us/worldwide.aspx