= SpringFox Grails Integration

image:https://api.bintray.com/packages/springfox/maven-repo/springfox-grails-integration/images/download.svg["Download", link="https://bintray.com/springfox/maven-repo/springfox-grails-integration/_latestVersion"] image:https://circleci.com/gh/springfox/springfox-grails-integration.svg?style=svg["CircleCI", link="https://circleci.com/gh/springfox/springfox-grails-integration"] image:https://codecov.io/gh/springfox/springfox-grails-integration/branch/master/graph/badge.svg["codecov",link="https://codecov.io/gh/springfox/springfox-grails-integration"] image:https://api.codacy.com/project/badge/Grade/77fbd793eb06447d9f1bf47eb8cdad8b["Codacy code quality", link="https://www.codacy.com/app/dilip-krishnan-github/springfox-grails-integration?utm_source=github.com&utm_medium=referral&utm_content=springfox/springfox-grails-integration&utm_campaign=Badge_Grade"] image:https://app.fossa.io/api/projects/git%2Bgithub.com%2Fspringfox%2Fspringfox-grails-integration.svg?type=shield["FOSSA Status", link="https://app.fossa.io/projects/git%2Bgithub.com%2Fspringfox%2Fspringfox-grails-integration?ref=badge_shield"]

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"]

Springfox Grails Integration

SpringFox integration with Grails 3.x

Springfox Grails Integration Info

⭐ Stars16
🔗 Source Codegithub.com
🕒 Last Update2 years ago
🕒 Created6 years ago
🐞 Open Issues29
➗ Star-Issue Ratio1
😎 Authorspringfox