Layer7 API Management

Expand all | Collapse all

Custom Documentation

  • 1.  Custom Documentation

    Posted 10-28-2015 05:24 PM

    Hello,

     

    Is there a way for me to add my own custom documentation for an API?  I plan on making heavy use of RAML and I have RAML to HTML generation tooling that I'd like to use to produce my docs.  I'd like to be able to host this HTML on the portal if at all possible.  Any hints?

     

    Thanks,

     

    Alejandro



  • 2.  Re: Custom Documentation

    Posted 10-28-2015 08:41 PM

    Hi Alejandro,

     

    The Add API Wizard in the Portal allows you to upload a RAML file which is used to automatically generate the interactive documentation: https://wiki.ca.com/display/APIDP31/Use+the+Add+API+Wizard+to+Publish+APIs .

     

    You an also create your own Portal content.  I usually do this in the Staging mode: Work in Staging Mode - CA API Developer Portal - 3.1 - CA Technologies Documentation .  You should be able to paste in the HTML directly into the section editor in this mode.

     

    The combination of these 2 functions should get you what you're looking for.

     

    Cheers,

    Julian



  • 3.  Re: Custom Documentation

    Posted 10-29-2015 12:11 PM

    Thanks.  I think I understand what you've proposed.  One option is the API wizard where I can add RAML or WADL to generate interactive docs.  The other is to manually add content through the CMS.

     

    I was hoping that using the CMS would allow me to add HTML, but this isn't the behavior that I'm seeing.  Here is what I did:

    • Navigated to Documentation landing page
    • Entered staging mode
    • Added a new page using the "general" page template
    • Added a new section
    • Edited section in standalone mode by adding HTML (simple <b>foo</b>)
    • Saved section

     

    The content that was rendered was escaped HTML showing the text above.  Is there something that I am missing?

     

    The docs also referenced a way to use the iframe to reference 3rd party content.  This might be what I'm after since, in theory, I could host my docs on another server if I can't add my content directly through the CMS.

     

    Thanks!

     

    Alejandro



  • 4.  Re: Custom Documentation

    Posted 10-29-2015 12:36 PM

    Hi Alejandro,

     

    You have to hit the source button to view the raw HTML.  So if your page looks like this:

    Screen Shot 2015-10-29 at 9.32.35 AM.png

    ...hitting the Source button will show you this:

    Screen Shot 2015-10-29 at 9.32.25 AM.png

     

    One other option I should have mentioned in my earlier post is to reference an external page using iFrame.

     

    Cheers,

    Julian



  • 5.  Re: Custom Documentation

    Posted 10-29-2015 01:20 PM

    Ah, got it.  Looks like this approach reformats the source content (wraps it in a para tags and strips out script tags, maybe others).

     

    IFrame is interesting, but its a bit messy.  Is there a way to have the CMS retain my content (script tags and all)?  Otherwise, I might have to resort to linking out to external content.

     

    Thanks!

     

    Alejandro



  • 6.  Re: Custom Documentation

    Posted 10-29-2015 03:07 PM

    I'm not aware of a way to upload your content as is. To leverage JS scripts what I do is place them in a separate .js file and upload this to the CMS (I usually put them in /resources/sites/api-portal/scripts).  Once your scripts are uploaded to the CMS you have to make your custom page aware of it.  You can do this by dropping down to staging mode and selecting Page Resources:

    Screen Shot 2015-10-29 at 12.04.07 PM.png

    ...and then choosing Add Item to reference your JS scripts:

    Screen Shot 2015-10-29 at 12.04.23 PM.png

     

    This requires a number of manual steps - but will allow you to reference your scripts. 



  • 7.  Re: Custom Documentation

    Posted 03-03-2016 05:27 PM

    I think underlying CMS really sucks, and it is better to escape from it as much as possible. There is underlying tomcat that hosts API portal and you could simply serve your documents inside it by defining docBase directive in server.xml file : exact path is like /opt/Deployments/lrs/server/conf/server.xml.

     

     

    <Context docBase="/customhtmls" path="/custompages" />

     

    After server restart you should be able to access your files from : http://<PORTAL_IP>/custompages/* where your files are under /customhtmls

     

    You could then add one IFrame page pointing to your index.page.