Enunciate Javadoc Framework

Enunciate Javadoc Framework

Introduction

Enunciate is an open source framework, which is used to create documents for web service API. It is primarily a build-time tool, which helps Jersey, Metro, CXF or JBoss-WS to process the web service requests without any hindrance. Enunciate also avoids the pain of maintaining API document, thus generating the API documents in an easier way.

Use Case

Let’s have a use case on using Enunciate framework and integrate the framework to our existing or new implementation projects.

What we need to do:

  • Pre-requisites
  • Integrate Enunciate framework into web service projects.
  • Getting started.
  • Configure build.xml and web.xml.

Pre-requisites

  • Download  Enunciate  framework supporting jars from the link given below:

http://enunciate.codehaus.org/downloads.html

  • Extract zip file and jar files given below, to use it for jersey based API modules.

Integrate enunciate framework into web service projects

  • Web service project file structure:

package explorer

  • Create a new enunicate.xml file in the root of the project.
     
  • Setup the configurations into ant build.xml for generating war based on enunciate framework.
    • build.properties:
    • build.xml:

Note: it’s important to include $JAVA_HOME/lib/tools.jar on the classpath when invoking Enunciate.

  • Sample API from controller class: TestServiceController
  • Give proper java comments and explain about API details in initial controller.zz
    • Explain the service process overview and method of process.
    • Explain parameter detail, possible way of passing the input parameter and default values.
  • Building the projects
    • When the configuration is completed, build the application using ant build system.
    • Go to build.xml and execute ant target
    • Place the Default war files into tomcat/webapps folder
    • Once build function is completed, validate the recent war file placed in tomcat location

Now, start the tomcat server using ./startup batch files.

  • View the REST API’s  docs
    • Check the docs using server URL: http://localhost:8080/blogtest/index.html

In home page we will be able to see all the controller list : (Ex:TestServiceController)

WEB app

  • Click on the any controller name and it will redirect to  API list for corresponding  controller:

TSC

  • Click on the Mount Point, it will open new tab. We need to pass values in the parameter.

Hello world (2)

Conclusion

Enunciate framework is used to generate API report for web service project. This report initially lists out all the API’s list and every individual API has the following blocks.

  • Service name with available input parameter names
  • Service method (GET || POST)
  • Parameter’s name, supporting type, description and parameter default value.
  • Response type and response output format.

References

http://enunciate.codehaus.org/index.html

6490 Views 3 Views Today