springfox/springfox-grails-integration

= 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
```bash
./gradlew clean build publishToMavenLocal -i

== Getting Started

:releaseVersion: 1.0.0 :snapshotVersion: 1.0.1-SNAPSHOT :springfoxVersion: 2.7.0 :springfoxRfc6570Version: 1.0.0

The SpringFox Grails integration library depends on http://springfox.github.io/springfox/docs/current/[Springfox]

image:https://api.bintray.com/packages/springfox/maven-repo/springfox/images/download.svg["Download", link="https://bintray.com/springfox/maven-repo/springfox/_latestVersion"]

== Dependencies The Springfox libraries are hosted on https://bintray.com/springfox/maven-repo/springfox/view[bintray] and jcenter. The artifacts can be viewed accessed at the following locations:

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 http://springfox.github.io/springfox/docs/current/#swagger-ui[include springfox bundled swagger-ui] dependencies

NOTE: Please refer the main documentation on how to http://springfox.github.io/springfox/docs/current/#dependencies[include the springfox-swagger2 dependencies] which are required for this integration library to work.

=== Release [source,groovy] [subs="verbatim,attributes"]

repositories { jcenter() }

dependencies { compile "io.springfox.grails:springfox-grails:{releaseVersion}" //<1> }

=== Snapshot

[source,groovy] [subs="verbatim,attributes"]

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

dependencies { compile "io.springfox.grails:springfox-grails:{snapshotVersion}" //<1> }

== Configuration

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

[source,groovy] [subs="verbatim,attributes"]

// 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

[source,groovy] [subs="verbatim,attributes"]

repositories { jcenter() }

dependencies { compile "compile "io.springfox:springfox-swagger-ui:{springfoxVersion}" //<1> }

NOTE: The latest released version is image:https://api.bintray.com/packages/springfox/maven-repo/springfox/images/download.svg["Springfox Version", link="https://bintray.com/springfox/maven-repo/springfox/_latestVersion"]

== 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 https://github.com/springfox/springfox-grails-demo[this repository]. You can see a live demo running or https://immense-escarpment-17128.herokuapp.com/swagger-ui.html[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.

License

image:https://app.fossa.io/api/projects/git%2Bgithub.com%2Fspringfox%2Fspringfox-grails-integration.svg?type=large["FOSSA Status", link="https://app.fossa.io/projects/git%2Bgithub.com%2Fspringfox%2Fspringfox-grails-integration?ref=badge_large"]