Spring Boot 集成Swagger

版权声明：本文为博主原创文章，未经博主允许不得转载。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

更多关于Swagger的作用，相信大家百度一下能了解的更全面，本文以SpringBoot中集成Swagger为例做介绍说明。

一、修改pom.xml，添加maven依赖

        <!-- Swagger -->        <dependency>            <groupId>io.springfox</groupId>            <artifactId>springfox-swagger2</artifactId>            <version>2.6.1</version>        </dependency>        <dependency>            <groupId>io.springfox</groupId>            <artifactId>springfox-swagger-ui</artifactId>            <version>2.6.1</version>        </dependency>
1
2
3
4
5
6
7
8
9
10
11
12
1
2
3
4
5
6
7
8
9
10
11
12

二、添加Swagger配置类

package com.example.swaggerdemo;import static com.google.common.base.Predicates.or;import static springfox.documentation.builders.PathSelectors.regex;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import org.springframework.web.context.request.async.DeferredResult;import springfox.documentation.service.ApiInfo;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;/** * SwaggerConfig */@Configuration@EnableSwagger2public class SwaggerConfig {    /**     * SpringBoot默认已经将classpath:/META-INF/resources/和classpath:/META-INF/resources/webjars/映射     * 所以该方法不需要重写，如果在SpringMVC中，可能需要重写定义（我没有尝试）     * 重写该方法需要 extends WebMvcConfigurerAdapter     *      *///    @Override//    public void addResourceHandlers(ResourceHandlerRegistry registry) {//        registry.addResourceHandler("swagger-ui.html")//                .addResourceLocations("classpath:/META-INF/resources/");////        registry.addResourceHandler("/webjars/**")//                .addResourceLocations("classpath:/META-INF/resources/webjars/");//    }    /**     * 可以定义多个组，比如本类中定义把test和demo区分开了     * （访问页面就可以看到效果了）      *     */    @Bean    public Docket testApi() {        return new Docket(DocumentationType.SWAGGER_2)                .groupName("test")                .genericModelSubstitutes(DeferredResult.class)//                .genericModelSubstitutes(ResponseEntity.class)                .useDefaultResponseMessages(false)                .forCodeGeneration(true)                .pathMapping("/")// base，最终调用接口后会和paths拼接在一起                .select()                .paths(or(regex("/api/.*")))//过滤的接口                .build()                .apiInfo(testApiInfo());    }    @Bean    public Docket demoApi() {        return new Docket(DocumentationType.SWAGGER_2)                .groupName("demo")                .genericModelSubstitutes(DeferredResult.class)//              .genericModelSubstitutes(ResponseEntity.class)                .useDefaultResponseMessages(false)                .forCodeGeneration(false)                .pathMapping("/")                .select()                .paths(or(regex("/demo/.*")))//过滤的接口                .build()                .apiInfo(demoApiInfo());    }    private ApiInfo testApiInfo() {        return new ApiInfoBuilder()            .title("Electronic Health Record(EHR) Platform API")//大标题            .description("EHR Platform's REST API, all the applications could access the Object model data via JSON.")//详细描述            .version("1.0")//版本            .termsOfServiceUrl("NO terms of service")            .contact(new Contact("小单", "http://blog.csdn.net/catoop", "[e-mail]"))//作者            .license("The Apache License, Version 2.0")            .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")            .build();    }    private ApiInfo demoApiInfo() {        return new ApiInfoBuilder()            .title("Electronic Health Record(EHR) Platform API")//大标题            .description("EHR Platform's REST API, all the applications could access the Object model data via JSON.")//详细描述            .version("1.0")//版本            .termsOfServiceUrl("NO terms of service")            .contact(new Contact("小单", "http://blog.csdn.net/catoop", "[e-mail]"))//作者            .license("The Apache License, Version 2.0")            .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")            .build();        return apiInfo;    }}
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
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

经过这2步配置后，我们启动服务后，访问：http://localhost:8080/swagger-ui.html 就完成了集成。

Swagger会默认把所有Controller中的RequestMapping方法都生成API出来，实际上我们一般只需要标准接口的（像返回页面的那种Controller方法我们并不需要），所有你可以按下面的方法来设定要生成API的方法的要求。 
如下我针对RestController注解的类和ResponseBody注解的方法才生成Swaager的API，并且排除了特定的类，代码如下：

@Configuration@EnableSwagger2 // 启用 Swaggerpublic class SwaggerConfig {    @Bean    public Docket createRestApi() {        Predicate<RequestHandler> predicate = new Predicate<RequestHandler>() {            @Override            public boolean apply(RequestHandler input) {                Class<?> declaringClass = input.declaringClass();                if (declaringClass == BasicErrorController.class)// 排除                    return false;                if(declaringClass.isAnnotationPresent(RestController.class)) // 被注解的类                    return true;                if(input.isAnnotatedWith(ResponseBody.class)) // 被注解的方法                    return true;                return false;            }        };        return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(apiInfo())                .useDefaultResponseMessages(false)                .select()                .apis(predicate)                .build();    }    private ApiInfo apiInfo() {        return new ApiInfoBuilder()            .title("包含媒体、咨询、搜索引擎关键字、广告等类型接口的服务")//大标题            .version("1.0")//版本            .build();    }}
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
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

三、常见swagger注解一览与使用

最常用的5个注解

@Api：修饰整个类，描述Controller的作用@ApiOperation：描述一个类的一个方法，或者说一个接口@ApiParam：单个参数描述@ApiModel：用对象来接收参数@ApiProperty：用对象接收参数时，描述对象的一个字段
1
2
3
4
5
1
2
3
4
5

其它若干

@ApiResponse：HTTP响应其中1个描述@ApiResponses：HTTP响应整体描述@ApiIgnore：使用该注解忽略这个API @ApiClass@ApiError@ApiErrors@ApiParamImplicit@ApiParamsImplicit
1
2
3
4
5
6
7
8
9
10
1
2
3
4
5
6
7
8
9
10

下面创建2个Controller来测试： 
1、TestController.Java

@Controller@RequestMapping("/api/test")public class TestController {    @ResponseBody    @RequestMapping(value = "/show", method=RequestMethod.POST, produces=MediaType.APPLICATION_JSON_VALUE)// 这里指定RequestMethod，如果不指定Swagger会把所有RequestMethod都输出，在实际应用中，具体指定请求类型也使接口更为严谨。    @ApiOperation(value="测试接口", notes="测试接口详细描述")    public String show(            @ApiParam(required=true, name="name", value="姓名")            @RequestParam(name = "name", required=true) String stuName){        return "success";    }}
1
2
3
4
5
6
7
8
9
10
11
12
13
1
2
3
4
5
6
7
8
9
10
11
12
13

2、DemoController.java

/** * DemoController *  */@Controller@RequestMapping(value = "/demo")public class DemoController {    private Logger logger = LoggerFactory.getLogger(DemoController.class);    /**     * 可以直接使用@ResponseBody响应JSON     *      * @param request     * @param response     * @return     */    @ResponseBody    @RequestMapping(value = "/getcount", method = RequestMethod.POST)    @ApiOperation(value="测试-getCount", notes="getCount更多说明")    public ModelMap getCount(HttpServletRequest request,            HttpServletResponse response) {        logger.info(">>>>>>>> begin getCount >>>>>>>>");        ModelMap map = new ModelMap();        map.addAttribute("count", 158);        // 后台获取的国际化信息        map.addAttribute("xstest", "测试");        return map;    }    /**     * 可以直接使用@ResponseBody响应JSON     *      * @param request     * @param response     * @return     */    @ApiIgnore//使用该注解忽略这个API    @ResponseBody    @RequestMapping(value = "/jsonTest1", method = RequestMethod.POST)    public ModelMap jsonTest(HttpServletRequest request,            HttpServletResponse response) {        ModelMap map = new ModelMap();        map.addAttribute("hello", "你好");        map.addAttribute("veryGood", "很好");        return map;    }    /**     * 可以直接使用@ResponseBody响应JSON     *      * @param request     * @param response     * @return     */    @ResponseBody    @RequestMapping(value = "/jsonTest3", method = RequestMethod.POST)    public List<String> jsonTest3(HttpServletRequest request,            HttpServletResponse response) {        List<String> list = new ArrayList<String>();        list.add("hello");        list.add("你好");        return list;    }    /**     * JSON请求一个对象<br/>     * （Ajax Post Data：{"name":"名称","content":"内容"}）     *      * @param version     * @return     */    @ResponseBody    @RequestMapping(value = "/jsonTest2", method = RequestMethod.POST)    public ModelMap jsonTest2(@RequestBody Demo demo) {        logger.info("demoName：" + demo.getName());        logger.info("demoContent：" + demo.getContent());        ModelMap map = new ModelMap();        map.addAttribute("result", "ok");        return map;    }    /**     * 直接读取URL参数值<br/>     * /demo/jsonTest6.do?name=Hello&content=World     *      * @param demoName     * @param content     * @return     */    @ResponseBody    @RequestMapping(value = "/jsonTest6", method = RequestMethod.POST)    public ModelMap jsonTest6(@RequestParam("name") String demoName, @RequestParam String content) {        logger.info("demoName：" + demoName);        ModelMap map = new ModelMap();        map.addAttribute("name",demoName + "AAA");        map.addAttribute("content",content + "BBB");        map.addAttribute("date",new java.util.Date());        return map;    }    /**     * JSON请求一个对象，将RequestBody自动转换为JSONObject对象<br/>     * （Ajax Post Data：{"name":"名称","content":"内容"}）     *      * 使用JSONObject请添加依赖     *  <dependency>     *      <groupId>net.sf.json-lib</groupId>     *      <artifactId>json-lib</artifactId>     *      <version>2.4</version>     *      <!--指定jdk版本 -->     *      <classifier>jdk15</classifier>     *  </dependency>     *      * @param version     * @return     */    @ResponseBody    @RequestMapping(value = "/jsonTest5", method = RequestMethod.POST)    public ModelMap jsonTest5(@RequestBody JSONObject jsonObject) {        String name = jsonObject.getString("name");        logger.info("demoName：" + name);        ModelMap map = new ModelMap();        map.addAttribute("demoName",name);        return map;    }    /**     * 输入 和输出为JSON格式的数据的方式 HttpEntity<?> ResponseEntity<?>     *      * @param u     * @return     */    @ResponseBody    @RequestMapping(value = "/jsonTest4", method = RequestMethod.POST)    public ResponseEntity<String> jsonTest4(HttpEntity<Demo> demo,            HttpServletRequest request, HttpSession session) {        //获取Headers方法        HttpHeaders headers = demo.getHeaders();        // 获取内容        String demoContent = demo.getBody().getContent();        // 这里直接new一个对象（HttpHeaders headers = new HttpHeaders();）        HttpHeaders responseHeaders = new HttpHeaders();        responseHeaders.add("MyHeaderName", "SHANHY");        ResponseEntity<String> responseResult = new ResponseEntity<String>(                demoContent, responseHeaders, HttpStatus.OK);        return responseResult;    }}
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
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

Swagger2默认将所有的Controller中的RequestMapping方法都会暴露，然而在实际开发中，我们并不一定需要把所有API都提现在文档中查看，这种情况下，使用注解@ApiIgnore来解决，如果应用在Controller范围上，则当前Controller中的所有方法都会被忽略，如果应用在方法上，则对应用的方法忽略暴露API。

注解@ApiOperation和@ApiParam可以理解为API说明，多动手尝试就很容易理解了。 
如果我们不使用这样注解进行说明，Swagger2也是有默认值的，没什么可说的试试就知道了。

在 http://localhost:8080/swagger-ui.html 显示页面的右上角有api_key ，springfox-swagger 2.2.2 版本并没有进行处理，我们可以自己添加拦截器拦截 /v2/api-docs 来处理我们API文档的访问权限，如果要更严格更灵活的控制，可能需要修改源码来实现了。相信 springfox-swagger 的后期版本应该会支持更全面的应用需求的。