swagger demo 完成，使用 swagger 管理 API

README.md

@@ -1,6 +1,6 @@
 # Spring Boot Demo
 
-spring boot demo 一个用来学习 spring boot 的项目，已经集成 actuator、logback、jpa、mybatis、redis缓存 模块，后续会集成activemq,email, freemarker,shiro,websocket,quartz,springfox,swagger,netty等模块。
+spring boot demo 一个用来学习 spring boot 的项目，已经集成 actuator、logback、jpa、mybatis、redis缓存、swagger模块，后续会集成activemq,email, freemarker,shiro,websocket,quartz,netty等模块。
 
 依赖的 Spring Boot 版本：
 
@@ -41,6 +41,7 @@ spring boot demo 一个用来学习 spring boot 的项目，已经集成 actuato
 		<module>../spring-boot-demo-jpa</module>
 		<module>../spring-boot-demo-mybatis</module>
 		<module>../spring-boot-demo-cache-redis</module>
+		<module>../spring-boot-demo-swagger</module>
 	</modules>
 
 	<parent>
@@ -134,6 +135,7 @@ spring boot demo 一个用来学习 spring boot 的项目，已经集成 actuato
 | [spring-boot-demo-jpa](./spring-boot-demo-jpa) | spring-boot 集成 spring-boot-starter-data-jpa 操作数据库 |
 | [spring-boot-demo-mybatis](./spring-boot-demo-mybatis) | spring-boot 集成 [mybatis-spring-boot-starter](https://github.com/mybatis/spring-boot-starter)、[mybatis-spring-boot-starter](https://github.com/alibaba/druid/tree/master/druid-spring-boot-starter) |
 | [spring-boot-demo-cache-redis](./spring-boot-demo-cache-redis) | spring-boot 使用 Redis 做缓存                 |
+| [spring-boot-demo-swagger](./spring-boot-demo-swagger) | spring-boot 集成 [spring-boot-starter-swagger](https://github.com/SpringForAll/spring-boot-starter-swagger) (由大佬[翟永超](http://blog.didispace.com/)开源)用于统一管理、测试 API 接口 |
 
 # 官方提供的 starter 介绍
 

spring-boot-demo-parent/pom.xml

@@ -19,6 +19,7 @@
 		<module>../spring-boot-demo-jpa</module>
 		<module>../spring-boot-demo-mybatis</module>
 		<module>../spring-boot-demo-cache-redis</module>
+		<module>../spring-boot-demo-swagger</module>
 	</modules>
 
 	<parent>

spring-boot-demo-swagger/README.md

@@ -0,0 +1,174 @@
+# spring-boot-demo-swagger
+
+依赖 [spring-boot-demo-parent](../spring-boot-demo-parent)、[spring-boot-starter-swagger](https://github.com/SpringForAll/spring-boot-starter-swagger) (由大佬[翟永超](http://blog.didispace.com/)开源)
+
+### pom.xml
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+	<modelVersion>4.0.0</modelVersion>
+
+	<artifactId>spring-boot-demo-swagger</artifactId>
+	<version>0.0.1-SNAPSHOT</version>
+	<packaging>jar</packaging>
+
+	<name>spring-boot-demo-swagger</name>
+	<description>Demo project for Spring Boot</description>
+
+	<parent>
+		<groupId>com.xkcoding</groupId>
+		<artifactId>spring-boot-demo-parent</artifactId>
+		<version>0.0.1-SNAPSHOT</version>
+		<relativePath>../spring-boot-demo-parent/pom.xml</relativePath>
+	</parent>
+
+	<properties>
+		<swagger.version>1.5.1.RELEASE</swagger.version>
+	</properties>
+
+	<dependencies>
+		<dependency>
+			<groupId>com.spring4all</groupId>
+			<artifactId>spring-boot-starter-swagger</artifactId>
+			<version>${swagger.version}</version>
+		</dependency>
+	</dependencies>
+
+	<build>
+		<finalName>spring-boot-demo-swagger</finalName>
+	</build>
+
+</project>
+```
+
+### application.yml
+
+```yml
+server:
+  port: 8080
+  context-path: /demo
+swagger:
+  # 是否启用swagger，默认：true
+  enabled: true
+  # 标题
+  title: swagger-demo API 管理
+  # 描述
+  description: 这里是 swagger-demo API 管理的描述信息
+  # 版本
+  version: 0.0.1-SNAPSHOT
+  # 许可证
+  license: MIT License
+  # 许可证URL
+  licenseUrl: https://github.com/xkcoding/spring-boot-demo/blob/master/LICENSE
+  # 许可证URL
+  termsOfServiceUrl: https://github.com/xkcoding/spring-boot-demo/blob/master/LICENSE
+  contact:
+      # 维护人
+      name: xkcoding
+      # 维护人URL
+      url: http://xkcoding.com
+      # 维护人URL
+      email: 237497819@qq.com
+  # swagger扫描的基础包，默认：全扫描
+  base-package: com.xkcoding
+  # 需要处理的基础URL规则，默认：/**
+  base-path: /**
+  # 需要排除的URL规则，默认：空
+  exclude-path: /error
+# swagger.host=文档的host信息，默认：空
+# swagger.globalOperationParameters[0].name=参数名
+# swagger.globalOperationParameters[0].description=描述信息
+# swagger.globalOperationParameters[0].modelRef=指定参数类型
+# swagger.globalOperationParameters[0].parameterType=指定参数存放位置,可选header,query,path,body.form
+# swagger.globalOperationParameters[0].required=指定参数是否必传，true,false
+```
+
+### SpringBootDemoSwaggerApplication.java
+
+```java
+@SpringBootApplication
+@EnableSwagger2Doc // 启用 Swagger
+public class SpringBootDemoSwaggerApplication {
+
+	public static void main(String[] args) {
+		SpringApplication.run(SpringBootDemoSwaggerApplication.class, args);
+	}
+}
+```
+
+### User.java
+
+```java
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+@ApiModel("用户基本信息")
+public class User {
+	private Long id;
+
+	@ApiModelProperty("姓名")
+	@Size(max = 20)
+	private String name;
+
+	@Max(value = 30, message = "年龄小于30岁才可以！")
+	@Min(value = 18, message = "你必须成年才可以！")
+	private Integer age;
+
+	@Pattern(regexp = "^\\w+([-+.]\\w+)*@\\w+([-.]\\w+)*\\.\\w+([-.]\\w+)*$", message = "邮箱格式错误！")
+	private String email;
+
+	@Pattern(regexp = "^(13[0-9]|14[5|7]|15[0|1|2|3|5|6|7|8|9]|18[0|1|2|3|5|6|7|8|9])\\d{8}$", message = "请输入正确的手机格式！")
+	private String phone;
+}
+```
+
+### UserController.java
+
+```java
+@Api(tags = "用户管理")
+@RestController
+@RequestMapping("/user")
+public class UserController {
+
+	@ApiOperation("新增用户")
+	@PostMapping({"", "/"})
+	public User insert(@RequestBody @Valid User user) {
+		return user;
+	}
+
+	@ApiIgnore
+	@DeleteMapping("/{id}")
+	public String deleteById(@PathVariable Long id) {
+		return "已删除用户 --> " + id;
+	}
+
+	@ApiOperation("修改用户详情")
+	@PutMapping("/{id}")
+	public User update(@PathVariable Long id, @RequestBody @Valid User user) {
+		user.setId(id);
+		return user;
+	}
+
+	@ApiOperation("用户详情")
+	@GetMapping("/{id}")
+	public User findById(@PathVariable Long id) {
+		return new User(id, "xkcoding" + id, 21, StrUtil.format("xkcoding{}@163.com", id), StrUtil.fill("186", id.toString().charAt(0), 11, false));
+	}
+
+	@ApiOperation("用户列表")
+	@GetMapping({"", "/"})
+	public List<User> index(@ApiParam("第几页") @RequestParam(defaultValue = "1") Integer pageNum, @ApiParam("每页的条目数") @RequestParam(defaultValue = "20") Integer pageSize) {
+		List<User> users = Lists.newArrayList();
+		users.add(new User(0L, "xkcoding0", 18, "xkcoding0@163.com", "18600000000"));
+		users.add(new User(1L, "xkcoding1", 19, "xkcoding1@163.com", "18611111111"));
+		return users;
+	}
+
+}
+```
+
+### 附上大佬(翟永超)博客关于 swagger 的一些文章
+
+http://blog.didispace.com/tags/Swagger/

spring-boot-demo-swagger/pom.xml

@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+	<modelVersion>4.0.0</modelVersion>
+
+	<artifactId>spring-boot-demo-swagger</artifactId>
+	<version>0.0.1-SNAPSHOT</version>
+	<packaging>jar</packaging>
+
+	<name>spring-boot-demo-swagger</name>
+	<description>Demo project for Spring Boot</description>
+
+	<parent>
+		<groupId>com.xkcoding</groupId>
+		<artifactId>spring-boot-demo-parent</artifactId>
+		<version>0.0.1-SNAPSHOT</version>
+		<relativePath>../spring-boot-demo-parent/pom.xml</relativePath>
+	</parent>
+
+	<properties>
+		<swagger.version>1.5.1.RELEASE</swagger.version>
+	</properties>
+
+	<dependencies>
+		<dependency>
+			<groupId>com.spring4all</groupId>
+			<artifactId>spring-boot-starter-swagger</artifactId>
+			<version>${swagger.version}</version>
+		</dependency>
+	</dependencies>
+
+	<build>
+		<finalName>spring-boot-demo-swagger</finalName>
+	</build>
+
+</project>

spring-boot-demo-swagger/src/main/java/com/xkcoding/springbootdemoswagger/SpringBootDemoSwaggerApplication.java

@@ -0,0 +1,14 @@
+package com.xkcoding.springbootdemoswagger;
+
+import com.spring4all.swagger.EnableSwagger2Doc;
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+@SpringBootApplication
+@EnableSwagger2Doc // 启用 Swagger
+public class SpringBootDemoSwaggerApplication {
+
+	public static void main(String[] args) {
+		SpringApplication.run(SpringBootDemoSwaggerApplication.class, args);
+	}
+}

spring-boot-demo-swagger/src/main/java/com/xkcoding/springbootdemoswagger/controller/UserController.java

@@ -0,0 +1,54 @@
+package com.xkcoding.springbootdemoswagger.controller;
+
+import com.google.common.collect.Lists;
+import com.xiaoleilu.hutool.util.StrUtil;
+import com.xkcoding.springbootdemoswagger.model.User;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiParam;
+import org.springframework.web.bind.annotation.*;
+import springfox.documentation.annotations.ApiIgnore;
+
+import javax.validation.Valid;
+import java.util.List;
+
+@Api(tags = "用户管理")
+@RestController
+@RequestMapping("/user")
+public class UserController {
+
+	@ApiOperation("新增用户")
+	@PostMapping({"", "/"})
+	public User insert(@RequestBody @Valid User user) {
+		return user;
+	}
+
+	@ApiIgnore
+	@DeleteMapping("/{id}")
+	public String deleteById(@PathVariable Long id) {
+		return "已删除用户 --> " + id;
+	}
+
+	@ApiOperation("修改用户详情")
+	@PutMapping("/{id}")
+	public User update(@PathVariable Long id, @RequestBody @Valid User user) {
+		user.setId(id);
+		return user;
+	}
+
+	@ApiOperation("用户详情")
+	@GetMapping("/{id}")
+	public User findById(@PathVariable Long id) {
+		return new User(id, "xkcoding" + id, 21, StrUtil.format("xkcoding{}@163.com", id), StrUtil.fill("186", id.toString().charAt(0), 11, false));
+	}
+
+	@ApiOperation("用户列表")
+	@GetMapping({"", "/"})
+	public List<User> index(@ApiParam("第几页") @RequestParam(defaultValue = "1") Integer pageNum, @ApiParam("每页的条目数") @RequestParam(defaultValue = "20") Integer pageSize) {
+		List<User> users = Lists.newArrayList();
+		users.add(new User(0L, "xkcoding0", 18, "xkcoding0@163.com", "18600000000"));
+		users.add(new User(1L, "xkcoding1", 19, "xkcoding1@163.com", "18611111111"));
+		return users;
+	}
+
+}

spring-boot-demo-swagger/src/main/java/com/xkcoding/springbootdemoswagger/model/User.java

@@ -0,0 +1,34 @@
+package com.xkcoding.springbootdemoswagger.model;
+
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import javax.validation.constraints.Max;
+import javax.validation.constraints.Min;
+import javax.validation.constraints.Pattern;
+import javax.validation.constraints.Size;
+
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+@ApiModel("用户基本信息")
+public class User {
+	private Long id;
+
+	@ApiModelProperty("姓名")
+	@Size(max = 20)
+	private String name;
+
+	@Max(value = 30, message = "年龄小于30岁才可以！")
+	@Min(value = 18, message = "你必须成年才可以！")
+	private Integer age;
+
+	@Pattern(regexp = "^\\w+([-+.]\\w+)*@\\w+([-.]\\w+)*\\.\\w+([-.]\\w+)*$", message = "邮箱格式错误！")
+	private String email;
+
+	@Pattern(regexp = "^(13[0-9]|14[5|7]|15[0|1|2|3|5|6|7|8|9]|18[0|1|2|3|5|6|7|8|9])\\d{8}$", message = "请输入正确的手机格式！")
+	private String phone;
+}

spring-boot-demo-swagger/src/main/resources/application.yml

@@ -0,0 +1,37 @@
+server:
+  port: 8080
+  context-path: /demo
+swagger:
+  # 是否启用swagger，默认：true
+  enabled: true
+  # 标题
+  title: swagger-demo API 管理
+  # 描述
+  description: 这里是 swagger-demo API 管理的描述信息
+  # 版本
+  version: 0.0.1-SNAPSHOT
+  # 许可证
+  license: MIT License
+  # 许可证URL
+  licenseUrl: https://github.com/xkcoding/spring-boot-demo/blob/master/LICENSE
+  # 许可证URL
+  termsOfServiceUrl: https://github.com/xkcoding/spring-boot-demo/blob/master/LICENSE
+  contact:
+      # 维护人
+      name: xkcoding
+      # 维护人URL
+      url: http://xkcoding.com
+      # 维护人URL
+      email: 237497819@qq.com
+  # swagger扫描的基础包，默认：全扫描
+  base-package: com.xkcoding
+  # 需要处理的基础URL规则，默认：/**
+  base-path: /**
+  # 需要排除的URL规则，默认：空
+  exclude-path: /error
+# swagger.host=文档的host信息，默认：空
+# swagger.globalOperationParameters[0].name=参数名
+# swagger.globalOperationParameters[0].description=描述信息
+# swagger.globalOperationParameters[0].modelRef=指定参数类型
+# swagger.globalOperationParameters[0].parameterType=指定参数存放位置,可选header,query,path,body.form
+# swagger.globalOperationParameters[0].required=指定参数是否必传，true,false

spring-boot-demo-swagger/src/test/java/com/xkcoding/springbootdemoswagger/SpringBootDemoSwaggerApplicationTests.java

@@ -0,0 +1,16 @@
+package com.xkcoding.springbootdemoswagger;
+
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.test.context.junit4.SpringRunner;
+
+@RunWith(SpringRunner.class)
+@SpringBootTest
+public class SpringBootDemoSwaggerApplicationTests {
+
+	@Test
+	public void contextLoads() {
+	}
+
+}