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

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

1.5.1. Snapshot

This is normally done by the CI server

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

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=<MAJOR|MINOR|PATCH>
 --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

<repositories>
    <repository>
      <id>jcenter-snapshots</id>
      <name>jcenter</name>
      <url>https://jcenter.bintray.com/</url>
    </repository>
</repositories>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>

Snapshot

<repositories>
    <repository>
      <id>jcenter-snapshots</id>
      <name>jcenter</name>
      <url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
    </repository>
</repositories>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.2-SNAPSHOT</version>
</dependency>

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)"/")String.class)WildcardType.class)),
                typeResolver.resolve(WildcardType.class)))false)new ResponseMessageBuilder()
                .code(500)
                .message("500 message")
                .responseModel(new ModelRef("Error"))true)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")) @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.*"))List<SecurityReference> 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