README.adoc

SpringFox Grails Integration

SpringFox Grails integration library that produces grails specific documentation.

Development Environment

IDE setup

IntelliJ IDEA

• File >> open >> build.gradle

• Make sure to check the 'use the default gradle wrapper' option.

• First time build

./gradlew cleanIdea idea

Build

• To get more output from any gradle commands/tasks append a -i (info) or -d (debug) e.g.

./gradlew clean build -i

• To publish to local maven repository

./gradlew clean build publishToMavenLocal -i

Getting Started

The SpringFox Grails integration library depends on Springfox

Dependencies

The Springfox libraries are hosted on bintray and jcenter. The artifacts can be viewed accessed at the following locations:

• Release:

  • https://jcenter.bintray.com/io/springfox/

  • http://jcenter.bintray.com/io/springfox/

• Snapshot

  • http://oss.jfrog.org/simple/oss-snapshot-local/io/springfox/

  • http://oss.jfrog.org/oss-snapshot-local/io/springfox/

SpringFox has multiple modules and the dependencies will vary depending on the desired API specification standard. Below outlines how to include the springfox-swagger2 module which produces Swagger 2.0 API documentation.

Tip	Refer the main documentation on how to include springfox bundled swagger-ui dependencies

Note	Please refer the main documentation on how to include the springfox-swagger2 dependencies which are required for this integration library to work.

Release

repositories {
  jcenter()
}

dependencies {
    compile "io.springfox.grails:springfox-grails:1.0.0" //(1)
}

Snapshot

repositories {
   maven { url 'http://oss.jfrog.org/artifactory/oss-snapshot-local/' }
}

dependencies {
    compile "io.springfox.grails:springfox-grails:1.0.1-SNAPSHOT" //(1)
}

Configuration

In your Application (GrailsAutoConfiguration) startup entry-point follow the steps below

// 1. Enable SpringFox on your project
@EnableSwagger2
// 2. Import the springfox grails integration configuration
@Import([springfox.documentation.grails.SpringfoxGrailsIntegrationConfiguration])
class Application extends GrailsAutoConfiguration {
  static void main(String[] args) {
    GrailsApp.run(Application, args)
  }

  // 3. **Optionally** define a custom docket or omit this step to use the default
  // For grails it is preferrable to use use the following settings.
  @Bean
  Docket api() {
    new Docket(DocumentationType.SWAGGER_2)
        .ignoredParameterTypes(MetaClass)
        .select()
        .paths(not(ant("/error")))
        .build()
  }

   // 4. **Optionally** in the absense of asset pipeline configure the swagger-ui webjar to serve the scaffolded
   swagger UI
   @Bean
   static WebMvcConfigurerAdapter webConfigurer() {
     new WebMvcConfigurerAdapter() {
       @Override
       void addResourceHandlers(ResourceHandlerRegistry registry) {
         if (!registry.hasMappingForPattern("/webjars/**")) {
           registry
               .addResourceHandler("/webjars/**")
               .addResourceLocations("classpath:/META-INF/resources/webjars/")
         }
         if (!registry.hasMappingForPattern("/swagger-ui.html")) {
           registry
               .addResourceHandler("/swagger-ui.html")
               .addResourceLocations("classpath:/META-INF/resources/swagger-ui.html")
         }
       }
      }
    }
}

Swagger UI integration

Important

In order to use the bundled swagger UI as explained in step 4 above. The following library needs to be included in the build.gradle

repositories {
  jcenter()
}

dependencies {
    compile "compile "io.springfox:springfox-swagger-ui:2.7.0" //(1)
}

Note	The latest released version is

Extensibility

The library comes with intelligent defaults imeplemented by DefaultGrailsAlternateTypeRuleConvention. However the defaults can be tweaked using one of these extensibility mechanisms. The following classes can be implemented and registered as a bean to augment default behavior.

• AlternateTypeRuleConvention - for adding custom conventions for replacing grails types

• GrailsPropertySelector - for overriding the selection of grails properties by the default convention

• GrailsPropertyTransformer - for overriding the transformer of the grails property

• GeneratedClassNamingStrategy - for naming the generated class mixins

Demo application

The demo application is available in this repository. You can see a live demo running or heroku here.

Troubleshooting

If you get an exception when you try to run your app, this might be because of the chosen profile for your application. If you use the rest-api profile, everything should be fine, but if you’ve chosen the web profile, it is likely that you have to add something like this.

grails.serverURL: http://localhost:8080

to your application.yml for the plugin to render absolute links.