Springfox Reference Documentation

1. 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.

1.1. History

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

1.2. Goals

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

• To extend support for spring technologies other than spring webmvc

• Philosophically, we want to discourage using (swagger-core) annotations that are not material to the service description at runtime. For e.g. the jackson annotations should always trump or have more weight than@ApiModelProperty or for e.g. @NotNull or specifying @RequestParam#required should always win. Annotations are to to be used only to supplement documentation or override/tweak the resulting spec in cases where its not possible to infer service/schema characteristics.

1.3. What it’s not

Endorsed or approved by the Spring Framework Contributors

1.4. 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 gradle commands/tasks append a -i (info) or -d (debug) e.g.

./gradlew build -i

• To publish to local maven repository

./gradlew clean build publishToMavenLocal -i

This build is optimized for releasing software to bintray/sonatype. In order for gradle to figure out the version the gradle plugin relies on local folder being a cloned git repository. Downloading the source archive and building will NOT work!

1.4.1. Pre-Commit Build

• Code quality (code coverage, checkstyle)

./gradlew check

1.4.2. Building reference documentation

To view the docs in a browser run:

./gradlew docs

When frequently generating the docs use the Gradle daemon as follows

 ./gradlew asciidoc --daemon

1.4.3. CI Environment

Circle CI

1.5. Releasing

To release a non-snapshot 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= -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

1.5.1. Snapshot

This is normally done by the CI server

./gradlew snapshot -PbintrayUsername= -PbintrayPassword=

1.5.2. 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=
 --stacktrace

1.5.3. Updating documentation

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

./gradlew publishDocs -PupdateMode

1.5.4. Contributing

Please see the wiki for some guidelines

1.6. Support

If you find issues or bugs please submit them via the Springfox Github project

2. Getting Started

2.1. 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.

2.1.1. Gradle

Release

repositories {
  jcenter()
}

dependencies {
    compile "io.springfox:springfox-swagger2:2.6.1"
}

Snapshot

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

dependencies {
    compile "io.springfox:springfox-swagger2:2.6.2-SNAPSHOT" }

2.1.2. Maven

Release

    
      jcenter-snapshots
      jcenter https://jcenter.bintray.com/    io.springfox springfox-swagger2 2.6.1 

Snapshot

    
      jcenter-snapshots
      jcenter http://oss.jfrog.org/artifactory/oss-snapshot-local/    io.springfox springfox-swagger2 2.6.2-SNAPSHOT 

2.1.3. Springfox-swagger2 with Spring MVC and Spring Boot

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155

/* * * Copyright 2015 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. * * */ package springfox.springconfig; import com.fasterxml.classmate.TypeResolver; import org.joda.time.LocalDate; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.context.ApplicationContext; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.ComponentScan; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.RequestMethod; import org.springframework.web.context.request.async.DeferredResult; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.builders.ResponseMessageBuilder; import springfox.documentation.builders.ParameterBuilder; import springfox.documentation.schema.ModelRef; import springfox.documentation.schema.WildcardType; import springfox.documentation.service.ApiKey; import springfox.documentation.service.AuthorizationScope; import springfox.documentation.service.SecurityReference; import springfox.documentation.service.Tag; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spi.service.contexts.SecurityContext; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger.web.ApiKeyVehicle; import springfox.documentation.swagger.web.SecurityConfiguration; import springfox.documentation.swagger.web.UiConfiguration; import springfox.documentation.swagger2.annotations.EnableSwagger2; import springfox.petstore.controller.PetController; import java.util.List; import static com.google.common.collect.Lists.*; import static springfox.documentation.schema.AlternateTypeRules.*; @SpringBootApplication @EnableSwagger2 @ComponentScan(basePackageClasses = { PetController.class }) public class Swagger2SpringBoot { public static void main(String[] args) { ApplicationContext ctx = SpringApplication.run(Swagger2SpringBoot.class, args); } @Bean public Docket petApi() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.any()) .paths(PathSelectors.any()) .build() .pathMapping("/") .directModelSubstitute(LocalDate.class, String.class) .genericModelSubstitutes(ResponseEntity.class) .alternateTypeRules( newRule(typeResolver.resolve(DeferredResult.class, typeResolver.resolve(ResponseEntity.class, WildcardType.class)), typeResolver.resolve(WildcardType.class))) .useDefaultResponseMessages(false) .globalResponseMessage(RequestMethod.GET, newArrayList(new ResponseMessageBuilder() .code(500) .message("500 message") .responseModel(new ModelRef("Error")) .build())) .securitySchemes(newArrayList(apiKey())) .securityContexts(newArrayList(securityContext())) .enableUrlTemplating(true) .globalOperationParameters( newArrayList(new ParameterBuilder() .name("someGlobalParameter") .description("Description of someGlobalParameter") .modelRef(new ModelRef("string")) .parameterType("query") .required(true) .build())) .tags(new Tag("Pet Service", "All apis relating to pets")) .additionalModels(typeResolver.resolve(AdditionalModel.class)) ; } @Autowired private TypeResolver typeResolver; private ApiKey apiKey() { return new ApiKey("mykey", "api_key", "header"); } private SecurityContext securityContext() { return SecurityContext.builder() .securityReferences(defaultAuth()) .forPaths(PathSelectors.regex("/anyPath.*")) .build(); } List defaultAuth() { AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything"); AuthorizationScope[] authorizationScopes = new AuthorizationScope[1]; authorizationScopes[0] = authorizationScope; return newArrayList( new SecurityReference("mykey", authorizationScopes)); } @Bean SecurityConfiguration security() { return new SecurityConfiguration( "test-app-client-id", "test-app-client-secret", "test-app-realm", "test-app", "apiKey", ApiKeyVehicle.HEADER, "api_key", "," /*scope separator*/); } @Bean UiConfiguration uiConfig() { return