Forum Discussion

wally's avatar
wally
New Contributor
5 years ago

Swagger to generate docs from Java API code

I need to automatically generate documentation from Java API code written by someone else using the Jersey framework. The project is built using Gradle. I'm trying to figure out how to use Swagger f...
frantuma's avatar
frantuma
Staff

The tutorial you linked is using springfox and as you mention it allows to generate Swagger documentation analyzing Spring based APIs impementation code.

 

swagger-core (wiki) provides a similar functionality for JAX-RS based code (e.g your Jersey based API code), supporting recommended OpenAPI 3.0.0 as well as previous Swagger/OpenAPI 2.0 format (in the 1.5 branch , refer to this wiki page)

 

 

wally's avatar
wally
New Contributor
5 years ago

After going through the articles I'm still not sure how to include Swagger in my project. I understand I need to add the dependency to the Swagger package but I don't know how exactly. I've tried adding these lines to the build.gradle file but can't see any effects:

plugins {
  id "io.swagger.core.v3.swagger-gradle-plugin" version "2.1.1"
}
  • frantuma's avatar
    frantuma
    Staff
    5 years ago

    This depends on what you want to achieve. The gradle config you shared ( I believe gotten from swagger-gradle-plugin README ) makes me think you want to build an OpenAPI specification out of JAX-RS based code as a file added to your project during build time. If this is the case you would define a gradle `resolve` task as described in README and execute it in your gradle build. 

     

    If your goal is instead exposing an OpenAPI specification at runtime at an URI like https://<yourserver>/../openapi.json, you would follow the main wiki (the only difference being declaring the dependencies in your gradle file instead of the maven POM

    • wally's avatar
      wally
      New Contributor
      5 years ago

      Yes, I'm trying to do the first option (documentation generated at build time).

      I'm afraid, I'll need some help with getting that 'resolve' task described (I'm not experienced with Gradle either). I see some code for the resolve task in the README page but I'm not sure where I'm supposed to add it. Somewhere in the build.gradle file, I presume, but where specifically?

      resolve {
    outputFileName = 'PetStoreAPI'
    outputFormat = 'JSON'
    prettyPrint = 'TRUE'
    classpath = sourceSets.main.runtimeClasspath
    resourcePackages = ['io.test']
    outputDir = file('test')
}