CA Service Management

Generate API Documentation for RESTful Services (14.1) 

04-07-2017 12:01 PM

For 14.1 both the jax-doclets-0.9.0.jar and jax-doclets-0.10.0.jar can be used to generate documentation for the RESTful Services.

 

Both generate roughly 4 times more documentation when the commands are run from an admin command window. (1856 vs 350 html docs)

While trying to change directories in an admin cmd window I found it necessary to us cd /d ... to change directories instead of just cd.

 

 

 

Both will also generate a convenient hyperlinked index to all 1800 docs within the 'pojo' folder when ran as admin. 

 

Two things of note from the screenshot below:

First: The library dynamically regenerates you documentation for you as you customize the schema. Just login and copy down the

newest version after cycling the service. (it really works! )

 

Second: The deploy command will fail to deploy the WAR file with a fatal error and your documentation may not generate at all or only partially

if you run the deploy command from a non-admin cmd window. 

 

 

Both the jax-doclets-0.9.0.jar and jax-doclets-0.10.0.jar are attached to save hunting them down

To use 10 just rename it 9.

Statistics
0 Favorited
35 Views
0 Files
0 Shares
0 Downloads

Tags and Keywords

Comments

05-12-2021 11:45 AM

can you upload the files again?
Thanks

02-27-2019 03:02 PM

Just wondering if there has been any update for this, as running into similar problem with a v17 dev system trying to generate the API docs, and don't have a particularly good way to get the v14 files on it

11-27-2018 01:48 PM

Hey Pusphith,

 

They are normally install specific (as you may have custom objects).

 

I'm working with Carlos offline on this to see if we can get the docs generated properly with some workaround that we came up with, on his end. If that works, we'll try to come up with a formal solution on the same.

 

Feel free to hit me up directly with a case# if you already have one open with support on this one

 

thank you 

_R

11-21-2018 10:19 AM

Hi All,

Can you provide the documentation under the doc folder for REST?

Thanks

11-15-2018 09:45 AM

Thanks Raghu,

 

I just opened a case: 01241550

Regards,

Carlos

11-15-2018 09:37 AM

hey folks,

 

I have raised a defect with our engineering on this one, as I'm seeing the same issue and right now there's no work around. I'll update this thread as soon as I hear something

 

_R

11-15-2018 09:03 AM

If I change to version 1.7 I get an error related to java version. Unsupported major.minor version 52.0.

 

This is happening with SDM 17.1

03-20-2018 01:06 PM

Thanks Raghu,

I took a shorter approach and copied the generated documentation from an r14.1 instance. I will keep your workaround as an alternate solution.

Cheers,

Lindsay

03-20-2018 12:43 PM

Hey Lindsay,

 

Assuming you already copied the needed jar file as mentioned here: Generate API Documentation for RESTful Services - CA Service Management - 17.1 - CA Technologies Documentation  ( jax-doclets-0.9.0.jar ),   the problem is with Java Run Time.

 

JRE 1.8 and above stopped distributing the needed doclet support the old way.  So the solution just for generating the documentation is to use JRE 1.7 (from 14.x ?).  While we sort this out, are you able to try this approach instead:

 

(Note: I copied JRE 1.7.0_10 from our 14.1 install to : C:/Progra~2/CA/SC/JRE/1.7.0_10  )

 

make a backup of pdm_rest_util.cmd  and change it to look like this:

 

 

REM @echo off
REM @(#)$Id: pdm_rest_util.cmd ASPEN.1 2012/01/04 11:13:15 aliab01 Exp $
REM --- REST WEB SERVICES UTILITY TOOL ---

REM /* Set NX_ROOT , JRE_INSTALL_DIR */
setlocal
set NX_TEMP_CMD=%TEMP%\setenv.cmd
nx_env -d NX_ROOT > %NX_TEMP_CMD%
REM nx_env -d NX_JRE_INSTALL_DIR >> %NX_TEMP_CMD%
echo SET NX_JRE_INSTALL_DIR=C:/Progra~2/CA/SC/JRE/JRE/JRE/1.7.0_10>> %NX_TEMP_CMD%
call %NX_TEMP_CMD%
del %NX_TEMP_CMD%

REM /* Build argument list */
set args=
:getargs
set args=%args% %1
shift
if not .%1 == . goto :getargs

REM /* Invoke the tool */
%NX_JRE_INSTALL_DIR%/bin/java -ea -classpath "%NX_ROOT%/java/lib/pdm_rest_util.jar;%NX_ROOT%/java/lib/slump.jar;%NX_ROOT%/java/lib/sd-utils.jar;%NX_ROOT%/java/lib/domsrvr_utils.jar;%NX_ROOT%/java/lib/log4j-1.2.15.jar;%NX_JRE_INSTALL_DIR%/lib/tools.jar;%NX_ROOT%/bopcfg/www/CATALINA_BASE_REST/lib/rest-core.jar;%NX_ROOT%/bopcfg/www/CATALINA_BASE_REST/lib/jax-doclets-0.9.0.jar;%NX_ROOT%/site/cfg" com.ca.ServicePlus.rest.restutil.Pdm_rest_util %args%
cd \

 

 

 

Hope this helps

_R

 

 

03-20-2018 11:39 AM

Works fine in r14.1, thanks. Fails to generate documentation in r17.1 showing the following stdout:

C:\PROGRA~2\CA\SERVIC~1\bin>pdm_rest_util.cmd -deploy
log4j:WARN No appenders could be found for logger (com.ca.ServicePlus.slump.NXenv).
log4j:WARN Please initialize the log4j system properly.
INFO: Pdm_rest_util started. Arguments: -deploy
INFO: Generating Java source files for all Majic factories to C:/PROGRA~2/CA/SERVIC~1\temp\REST_APP\source\
INFO: Compiling Java source files to C:/PROGRA~2/CA/SERVIC~1\temp\SDM-REST\WEB-INF\classes\
INFO: Deploying WAR file to C:/PROGRA~2/CA/SERVIC~1\bopcfg\www\CATALINA_BASE_REST\webapps\
INFO: Generating API documentation for REST services to C:/PROGRA~2/CA/SERVIC~1\doc\REST
INFO: Completed deploying WAR file.
java.lang.NoClassDefFoundError: com/sun/tools/doclets/internal/toolkit/util/DirectoryManager
        at com.lunatech.doclets.jax.Utils.classToPath(Utils.java:312)
        at com.lunatech.doclets.jax.jaxb.writers.JAXBClassWriter.getWriter(JAXBClassWriter.java:44)
        at com.lunatech.doclets.jax.jaxb.writers.JAXBClassWriter.<init>(JAXBClassWriter.java:39)
        at com.lunatech.doclets.jax.jaxb.model.JAXBClass.write(JAXBClass.java:237)
        at com.lunatech.doclets.jax.jaxb.JAXBDoclet.start(JAXBDoclet.java:106)
        at com.lunatech.doclets.jax.jaxb.JAXBDoclet.start(JAXBDoclet.java:93)
        at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
        at sun.reflect.NativeMethodAccessorImpl.invoke(Unknown Source)
        at sun.reflect.DelegatingMethodAccessorImpl.invoke(Unknown Source)
        at java.lang.reflect.Method.invoke(Unknown Source)
        at com.sun.tools.javadoc.DocletInvoker.invoke(DocletInvoker.java:310)
        at com.sun.tools.javadoc.DocletInvoker.start(DocletInvoker.java:189)
        at com.sun.tools.javadoc.Start.parseAndExecute(Start.java:366)
        at com.sun.tools.javadoc.Start.begin(Start.java:219)
        at com.sun.tools.javadoc.Start.begin(Start.java:205)
        at com.sun.tools.javadoc.Main.execute(Main.java:162)
        at com.ca.ServicePlus.rest.restutil.JavaDocGeneratorImpl.generate(JavaDocGeneratorImpl.java:217)
        at com.ca.ServicePlus.rest.restutil.Pdm_rest_util$RestJavaDocGenThread.run(Pdm_rest_util.java:656)
        at java.lang.Thread.run(Unknown Source)
Caused by: java.lang.ClassNotFoundException: com.sun.tools.doclets.internal.toolkit.util.DirectoryManager
        at java.net.URLClassLoader.findClass(Unknown Source)
        at java.lang.ClassLoader.loadClass(Unknown Source)
        at java.lang.ClassLoader.loadClass(Unknown Source)
        ... 19 more
java.lang.NullPointerException
        at com.lunatech.doclets.jax.jaxrs.JAXRSDoclet.<init>(JAXRSDoclet.java:73)
        at com.lunatech.doclets.jax.jaxrs.JAXRSDoclet.start(JAXRSDoclet.java:67)
        at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
        at sun.reflect.NativeMethodAccessorImpl.invoke(Unknown Source)
        at sun.reflect.DelegatingMethodAccessorImpl.invoke(Unknown Source)
        at java.lang.reflect.Method.invoke(Unknown Source)
        at com.sun.tools.javadoc.DocletInvoker.invoke(DocletInvoker.java:310)
        at com.sun.tools.javadoc.DocletInvoker.start(DocletInvoker.java:189)
        at com.sun.tools.javadoc.Start.parseAndExecute(Start.java:366)
        at com.sun.tools.javadoc.Start.begin(Start.java:219)
        at com.sun.tools.javadoc.Start.begin(Start.java:205)
        at com.sun.tools.javadoc.Main.execute(Main.java:162)
        at com.ca.ServicePlus.rest.restutil.JavaDocGeneratorImpl.generate(JavaDocGeneratorImpl.java:237)
        at com.ca.ServicePlus.rest.restutil.Pdm_rest_util$RestJavaDocGenThread.run(Pdm_rest_util.java:656)
        at java.lang.Thread.run(Unknown Source)
INFO: Completed generating API documentation.
INFO: Cleaning up temp directories.
INFO: Done.

 

C:\PROGRA~2\CA\SERVIC~1\bin>

Related Entries and Links

No Related Resource entered.