Swagger Javadoc
Link:
https://github.com/ryankennedy/swagger-jaxrs-doclet
Usage:
Allow swagger definition json file to begenerated on building the maven project. Add the following to your rest api project pom file
${project.build.outputDirectory}
-apiVersion1 -docBasePath /apidocs -apiBasePath https://api.stubhub.com/
mvn clean package output is generated in target/classes/apidocs
Pros:
Can generate swagger definition based on jax-rs annotations only, you don’t have to add any swagger annotations. Not invasive.
Limitation:
The default plugin provided supports only jdk 1.7 javadoc, you have to recompile the source with jdk 1.6 tools.jar to support 1.6 javadoc
If at class level, api path is declared as “/”,the api json file is not generated
This has been fixed by me by modifying the source code
If at class level, no path annotation isadded, the api json file is not generated
Swagger cxf integration
Link:
https://github.com/wordnik/swagger-core/wiki/Java-CXF-Quickstart
Usage:
Allow you to view swagger json definition at runtime, there is an additional swagger doc rest endpoint in additional to your original rest webservice
Maven dependencies
Cxf spring config file
The highlighted properties are important
You will see an additional endpoint in youwadl file and swagger json file in
http://
Pros:
API definitions are always most up to date,allow you to view swagger definition at run time
Limitations:
You need to add swagger annotations to yoursource
It will not work if:
You don’t have @Api annotation in yourservice class
You have @Api annotation but not any @ApiOperation in your service method
Certain API definitions are not generated properly,even annotations are there. (Not too sure about the reasons)
Swagger maven plugin
Link:
https://github.com/kongchen/swagger-maven-plugin
Usage:
Allow swagger definition json file to begenerated on building the maven project， similar to the Javadocplugin
https://raw.github.com/kongchen/api-doc-template/master/v2.0/markdown.mustache
The highlighted package specifies thepackage to scan for swagger apis
Mvn clean compile output is generated in generated/apidocs
Pros:
Can generate swagger API definition withoutserver running
Limitations:
You need to add swagger annotations to yoursource
It will not work if:
You don’t have @Api annotation in yourservice class