CODEWITHSUNDEEP
javamavenswagger
Daniel Kaplan
Daniel Kaplan

Reputation: 67360

How do I use the output of swagger-jaxrs-doclet to generate swagger documentation?

I'm very new to Swagger so I may have some of these details wrong. Swagger seems like a cool tool for generating REST documentation. But, I don't like that it's very invasive and requires me to put annotations on my java classes. I found this maven plugin named swagger-jaxrs-doclet that seems to generate these json files that I should be able to pass into swagger to generate the swagger documentation. The advantage is I don't need to put swagger annotations on any of my classes.

Unfortunately the swagger-jaxrs-doclet documentation doesn't tell me what to do next. Can someone show me how to take the output of swagger-jaxrs-doclet and generate swagger documentation from it? I need to do this in maven.

Upvotes: 2

Views: 4342

Answers (3)

g7p
g7p

Reputation: 126

Check out the "Usage section" on https://github.com/teamcarma/swagger-jaxrs-doclet - for examples for both maven and gradle.

Also, the "Example" section seems pretty straight forward; hence a bit un-sure what it is that you are looking for help with. If you could be a little more - " Can someone show me how to take the output of swagger-jaxrs-doclet and generate swagger documentation from it? I need to do this in maven."

As I understand the com.carma:swagger-doclet generates the necessary Swagger 1.2 resource description files and places them in the "build/reports/rest-api-docs" if you just use their example as is.

Upvotes: 1

Roy Kachouh
Roy Kachouh

Reputation: 1903

The way I set it up for my java project using gradle was the following:

1). Add a doclet configuration to build.grade

doclet(
      [group: 'com.carma', name: 'swagger-doclet', version: '1.0.4.2'],
      [group: 'javax.ws.rs', name: 'javax.ws.rs-api', version: '2.0']

)

2). Create a gradle task to generate the rest docs after the build task generateRestApiDocs(type: Javadoc) {

source = sourceSets.main.allJava
  def file = new File(project.rootDir.toString() + "/my-app/src/main/resources/assets/api-docs")

  destinationDir = file
  options.classpath = configurations.doclet.files.asType(List)
  options.docletpath = configurations.doclet.files.asType(List)
  options.doclet = "com.carma.swagger.doclet.ServiceDoclet"
  options.addStringOption("apiVersion", "1")
  options.addStringOption("docBasePath", "/assets/api-docs")
  options.addStringOption("apiBasePath", "../../")
  options.addBooleanOption("skipUiFiles", true)
  if (JavaVersion.current().isJava8Compatible()) {
    options.addStringOption('Xdoclint:none')
  }
 }

3). Make build depend on the generated rest docs task

build.dependsOn generateRestApiDocs

4). Annotate and javadoc your resources

/**
   * Endpoint to do something blah blah
   *
   * @param id blah blah blah
   * @param boolean blah blah blahb
   * @return {@link blab}
   * @responseMessage 200 ok
   * @responseMessage 404 not found
   */
  @GET
  @Produces(MediaType.APPLICATION_JSON)
  @Path("/{id}")

5). The build task will create the necessary swagger json files to be served out by your swagger ui.

Upvotes: 0

Nithin Reddy
Nithin Reddy

Reputation: 11

Just upload the apidocs or the dist folder (Based on which swagger-ui version you are using) on some local server and open from your browser. The javascript gets executed and you will see the output.

Upvotes: 1

Related Questions