https://github.com/jdcasey/restdoc-maven-plugin

Maven plugin for merging and transforming output of org.rhq.helper:rest-docs-generator annotation processor
https://github.com/jdcasey/restdoc-maven-plugin

Last synced: 11 months ago
JSON representation

Maven plugin for merging and transforming output of org.rhq.helper:rest-docs-generator annotation processor

• Host: GitHub
• URL: https://github.com/jdcasey/restdoc-maven-plugin
• Owner: jdcasey
• Created: 2013-05-10T22:16:16.000Z (about 13 years ago)
• Default Branch: master
• Last Pushed: 2013-05-11T02:20:33.000Z (about 13 years ago)
• Last Synced: 2025-09-09T07:29:39.253Z (11 months ago)
• Language: Java
• Size: 129 KB
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

          
# Restdoc Maven Plugin

This plugin aggregates and transforms XML metadata gleaned from annotation processing with [org.rhq.helper:rest-docs-generator](https://github.com/rhq-project/helpers), which uses annotations from the JAX-RS spec and from the [swagger](https://developers.helloreverb.com/swagger/) project to generate documentation about REST endpoints and datatypes. By default, it generates HTML output using a built-in stylesheet that was originally from [here](https://git.fedorahosted.org/cgit/rhq/rhq.git/tree/modules/enterprise/server/jar/src/main/xsl/apiout2html.xsl).

Currently, this is **A VERY RUDIMENTARY IMPLEMENTATION**. The best I can currently say about the generated HTML is that it's better than nothing. Marginally. However, the aggregated XML offers more promise, especially when coupled with a jQuery-driven UI.

## Build.

Building is simple: `mvn clean install`

## Use.

In your project's top-level POM, add this:

    

      

        com.wordnik

        swagger-annotations_2.9.1

        1.2.3

        provided

      

      

        org.rhq.helpers

        rest-docs-generator

        4.6.0

        provided

      

    

    [...]

    

      

        

          

            maven-compiler-plugin

            3.1

            

              

                generate-restdoc

                generate-resources

                

                  compile

                

                

                  

                    org.rhq.helpers.rest_docs_generator.ClassLevelProcessor

                  

                  only

                  

                    ${project.build.directory}/classes/META-INF/rest-docs

                    org.commonjava.aprox.model

                    

                    

                    true

                  

                  

                  false

                

              

            

          

          

            org.commonjava.maven

            restdoc-maven-plugin

            0.1-SNAPSHOT

            

              

                generate-html

                

                  generate

                

              

            

          

        

      

    

This will automatically attempt to process any classes in your project tree that have JAX-RS or Swagger annotations. Next, in your WAR module, add:

    

      

        

          

            maven-war-plugin

            

              

                

                  ${project.build.directory}/restdocs

                

              

            

          

        

      

      

        

          org.commonjava.maven

          restdoc-maven-plugin

        

      

    

When your build runs, your WAR should contain two new documents:

    /restdocs.html

    /restdocs.xml

The first is aggregated and transformed using the HTML XSLT stylesheet. The second is simply aggregated output from the annotation processor, which may be used from javascript or other UIs.

## Other Options.

Check `mvn org.commonjava.maven:restdoc-maven-plugin:0.1-SNAPSHOT:help` for more usage information.