Custom Documentation

[Alejandro Calbazana]

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

[Anon Anon]

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

[Alejandro Calbazana]

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

[Anon Anon]

Hi Alejandro,

 

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

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

 

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

 

Cheers,

Julian

[Alejandro Calbazana]

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

[Anon Anon]

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:

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

 

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

[Ozan Okan]

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.