Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/springfox/springfox-grails-integration

SpringFox integration with Grails 3.x
https://github.com/springfox/springfox-grails-integration

grails groovy oai spring springfox swagger

Last synced: 3 days ago
JSON representation

SpringFox integration with Grails 3.x

Awesome Lists containing this project

README 

        
= 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



```bash

./gradlew cleanIdea idea



```



=== Build



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

```bash

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



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