Introduction

The Springfox suite of java libraries are all about automating the generation of machine and human readable specifications for JSON APIs written using the spring family of projects. Springfox works by examining an application, once, at runtime to infer API semantics based on spring configurations, class structure and various compile time java Annotations.

History

Springfox has evolved from a project originally created by Marty Pitt and was named swagger-springmvc. Much kudos goes to Marty.

Goals

  1. To extend support for a number of the evolving standards targeted at JSON API specification and documentation such as: swagger, RAML and jsonapi.

  2. To extend support for spring technologies other than spring webmvc

What it’s not

Endorsed or approved by the Spring Framework Contributors

Development Environment

  • File >> open >> build.gradle

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

  • First time build

./gradlew cleanIdea idea

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

./gradlew build -i

Pre-Commit Build

  • Code quality (code coverage, checkstyle)

./gradlew check

Building reference documentation

 ./gradlew asciidoc --daemon //Using the gradle daemon here makes sense if this is being executed a lot

CI Enviroment

Circle CI

Releasing

To release a non-snaphot version of Springfox:

  • Execute the the release commands: The below properties are required to run a release:

  • GITHUB_TOKEN

  • BINTRAY_USERNAME

  • BINTRAY_PASSWORD

Recommend using [autoenv](https://github.com/kennethreitz/autoenv) with a .env file at the root of the repo.

    ./gradlew release publishDocs -PbintrayUsername=$BINTRAY_USERNAME -PbintrayPassword=$BINTRAY_PASSWORD
    -PreleaseType=<MAJOR|MINOR|PATCH> -i

The release steps are as follows: - check that the git workspace is clean - check that the local git branch is master - check that the local git branch is the same as origin - gradle test - gradle check - upload (publish) all artifacts to Bintray - Bumps the project version in version.properties - Git tag the release - Git push

Snapshot

This is normally done by the CI server

./gradlew snapshot -PbintrayUsername=<bintrayUsername> -PbintrayPassword=<bintrayPassword>

Override deploy

To bypass the standard release flow and upload directly to bintray use the following task - manually set the version in version.properties

./gradlew clean build bintrayUpload -PbintrayUsername=$BINTRAY_USERNAME -PbintrayPassword=$BINTRAY_PASSWORD -PreleaseType=<MAJOR|MINOR|PATCH>
 --stacktrace

Updating documentation

To update the docs for an existing release pass the updateMode switch

./gradlew publishDocs -PupdateMode

Contributing

Please see the wiki for some guidelines

Support

If you find issues or bugs please use the github issue springfox project