Generate the RESTful Webservice API documentation for CA Service Desk Manager 14.1

Products

• CA Service Management - Service Desk Manager
• CA Service Desk Manager

Issue/Introduction

The Restful webservice API documentation for CA Service Desk Manager is not shipped with the out of the box product.
But, in case you want to create your own SDM RESTful webservice application, you may need the sample syntax how to use the interface functions.
To create the documentation you must run the pdm_rest_util command and copy the "jax-doclets-0.9.0.jar" file/archive to the sdm java\lib.

The jar file is not shipped with CA Service Desk Manager. So you have to "GOOGLE" for it or use the CA communities link below.

I can't find the CA service Desk Manager (SDM) RESTFUL webservice API documentation?

How can I find it? 

Environment

W2k12; MS-SQLw2k14; SDM 14.1.02; nx.env file varibale points to CA SC (shared components java).Example: NX_JRE_INSTALL_DIR=C:/Program Files (x86)/CA/SC/JRE/1.7.0_10Java Release is 1.7

Resolution

Needed Environment:

W2k12; 

MS-SQLw2k14; 

SDM 14.1.02; 

nx.env file varibale points to CA SC (shared components java).

Example: NX_JRE_INSTALL_DIR=C:/Program Files (x86)/CA/SC/JRE/1.7.0_10

Java Release 1.7

 

Steps to do to generate the RESTful webservice API documentation:

1) download the doclets jar from this community entry:

   https://communities.ca.com/docs/DOC-231174222-generate-api-documentation-for-restful-services

Alt location for file "jax-doclets-0.9.0.jar"

https://github.com/FroMage/jax-doclets/downloads

 

2) copy "jax-doclets-0.9.0.jar" to %NX_ROOT%/java/lib 

3) stop SDM ; start SDM

4) open a command prompt in administrator mode

5) Run:  pdm_rest_util.cmd –undeploy

6) Run:  pdm_rest_util.cmd –deploy

7) verify that the api documentation is generated

 

Screenshots showing the result:

 

 

 

Additional Information

Community link: 

 https://communities.ca.com/docs/DOC-231174222-generate-api-documentation-for-restful-services

CA Online documentation link:

https://docops.ca.com/ca-service-management/14-1/en/reference/ca-service-desk-manager-reference-commands/generate-api-documentation-for-restful-services

PLEASE READ FOR VERSIONS ABOVE 17.1:

The above documentation was intended for up to SDM 17.1.  If one tries to run "pdm_rest_util - deploy" in a 17.3 environment, the following will result:

C:\PROGRA~2\CA\SERVIC~1>pdm_rest_util -deploy
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
javadoc: error - Cannot find doclet class com.lunatech.doclets.jax.jaxb.JAXBDoclet
javadoc: error - Cannot find doclet class com.lunatech.doclets.jax.jaxrs.JAXRSDoclet
INFO: Completed generating API documentation.
INFO: Completed deploying WAR file.
INFO: Cleaning up temp directories.
INFO: Done.

Even if one downloads and applies the "jax-doclets-0.9.0.jar", the above will fail on the javadoc creation step of "pdm_rest_util - deploy" 

C:\PROGRA~2\CA\SERVIC~1\java\lib>pdm_rest_util -deploy
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
javadoc: warning - The old Doclet and Taglet APIs in the packages
com.sun.javadoc, com.sun.tools.doclets and their implementations
are planned to be removed in a future JDK release. These
components have been superseded by the new APIs in jdk.javadoc.doclet.
Users are strongly recommended to migrate to the new APIs.
java.lang.NoClassDefFoundError: javax/xml/bind/annotation/XmlRootElement
        at com.lunatech.doclets.jax.jaxb.JAXBDoclet.<clinit>(JAXBDoclet.java:47)
        at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
        at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
        at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
        at java.base/java.lang.reflect.Method.invoke(Method.java:566)
        at jdk.javadoc/com.sun.tools.javadoc.main.DocletInvoker.invoke(DocletInvoker.java:333)
        at jdk.javadoc/com.sun.tools.javadoc.main.DocletInvoker.optionLength(DocletInvoker.java:236)
        at jdk.javadoc/com.sun.tools.javadoc.main.Start.parseAndExecute(Start.java:341)
        at jdk.javadoc/com.sun.tools.javadoc.main.Start.begin(Start.java:238)
        at jdk.javadoc/com.sun.tools.javadoc.main.Start.begin(Start.java:224)
        at jdk.javadoc/com.sun.tools.javadoc.Main.execute(Main.java:174)
        at jdk.javadoc/jdk.javadoc.internal.tool.Start.begin(Start.java:419)
        at jdk.javadoc/jdk.javadoc.internal.tool.Start.begin(Start.java:344)
        at jdk.javadoc/jdk.javadoc.internal.tool.Main.execute(Main.java:88)
        at jdk.javadoc/jdk.javadoc.internal.tool.JavadocToolProvider.run(JavadocToolProvider.java:45)
        at java.base/java.util.spi.ToolProvider.run(ToolProvider.java:137)
        at com.ca.ServicePlus.rest.restutil.JavaDocGeneratorImpl.generate(JavaDocGeneratorImpl.java:231)
        at com.ca.ServicePlus.rest.restutil.Pdm_rest_util$RestJavaDocGenThread.run(Pdm_rest_util.java:656)
        at java.base/java.lang.Thread.run(Thread.java:834)
Caused by: java.lang.ClassNotFoundException: javax.xml.bind.annotation.XmlRootElement
        at java.base/java.net.URLClassLoader.findClass(URLClassLoader.java:471)
        at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:588)
        at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:521)
        ... 19 more
javadoc: error - fatal error
1 error
javadoc: warning - The old Doclet and Taglet APIs in the packages
com.sun.javadoc, com.sun.tools.doclets and their implementations
are planned to be removed in a future JDK release. These
components have been superseded by the new APIs in jdk.javadoc.doclet.
Users are strongly recommended to migrate to the new APIs.
java.lang.NoClassDefFoundError: com/sun/tools/doclets/Taglet
        at java.base/java.lang.Class.getDeclaredMethods0(Native Method)
        at java.base/java.lang.Class.privateGetDeclaredMethods(Class.java:3166)
        at java.base/java.lang.Class.getMethodsRecursive(Class.java:3307)
        at java.base/java.lang.Class.getMethod0(Class.java:3293)
        at java.base/java.lang.Class.getMethod(Class.java:2106)
        at jdk.javadoc/com.sun.tools.javadoc.main.DocletInvoker.invoke(DocletInvoker.java:309)
        at jdk.javadoc/com.sun.tools.javadoc.main.DocletInvoker.optionLength(DocletInvoker.java:236)
        at jdk.javadoc/com.sun.tools.javadoc.main.Start.parseAndExecute(Start.java:341)
        at jdk.javadoc/com.sun.tools.javadoc.main.Start.begin(Start.java:238)
        at jdk.javadoc/com.sun.tools.javadoc.main.Start.begin(Start.java:224)
        at jdk.javadoc/com.sun.tools.javadoc.Main.execute(Main.java:174)
        at jdk.javadoc/jdk.javadoc.internal.tool.Start.begin(Start.java:419)
        at jdk.javadoc/jdk.javadoc.internal.tool.Start.begin(Start.java:344)
        at jdk.javadoc/jdk.javadoc.internal.tool.Main.execute(Main.java:88)
        at jdk.javadoc/jdk.javadoc.internal.tool.JavadocToolProvider.run(JavadocToolProvider.java:45)
        at java.base/java.util.spi.ToolProvider.run(ToolProvider.java:137)
        at com.ca.ServicePlus.rest.restutil.JavaDocGeneratorImpl.generate(JavaDocGeneratorImpl.java:241)
        at com.ca.ServicePlus.rest.restutil.Pdm_rest_util$RestJavaDocGenThread.run(Pdm_rest_util.java:656)
        at java.base/java.lang.Thread.run(Thread.java:834)
Caused by: java.lang.ClassNotFoundException: com.sun.tools.doclets.Taglet
        at java.base/java.net.URLClassLoader.findClass(URLClassLoader.java:471)
        at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:588)
        at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:521)
        ... 19 more
javadoc: error - fatal error
1 error
INFO: Completed generating API documentation.
INFO: Completed deploying WAR file.
INFO: Cleaning up temp directories.
INFO: Done.

This is due to the doclets APIs being deprecated for the later releases of JRE that are in place in the 17.3 builds.  Despite the lack of the REST documentation, this should not prevent one from using the REST functionality.