diff --git a/README.md b/README.md index b528ce4..57e531d 100644 --- a/README.md +++ b/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 ../spring-boot-demo-jpa ../spring-boot-demo-mybatis ../spring-boot-demo-cache-redis + ../spring-boot-demo-swagger @@ -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 介绍 diff --git a/spring-boot-demo-parent/pom.xml b/spring-boot-demo-parent/pom.xml index c82c408..df4cdef 100644 --- a/spring-boot-demo-parent/pom.xml +++ b/spring-boot-demo-parent/pom.xml @@ -19,6 +19,7 @@ ../spring-boot-demo-jpa ../spring-boot-demo-mybatis ../spring-boot-demo-cache-redis + ../spring-boot-demo-swagger diff --git a/spring-boot-demo-swagger/README.md b/spring-boot-demo-swagger/README.md new file mode 100644 index 0000000..05b896a --- /dev/null +++ b/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 + + + 4.0.0 + + spring-boot-demo-swagger + 0.0.1-SNAPSHOT + jar + + spring-boot-demo-swagger + Demo project for Spring Boot + + + com.xkcoding + spring-boot-demo-parent + 0.0.1-SNAPSHOT + ../spring-boot-demo-parent/pom.xml + + + + 1.5.1.RELEASE + + + + + com.spring4all + spring-boot-starter-swagger + ${swagger.version} + + + + + spring-boot-demo-swagger + + + +``` + +### 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 index(@ApiParam("第几页") @RequestParam(defaultValue = "1") Integer pageNum, @ApiParam("每页的条目数") @RequestParam(defaultValue = "20") Integer pageSize) { + List 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/ \ No newline at end of file diff --git a/spring-boot-demo-swagger/pom.xml b/spring-boot-demo-swagger/pom.xml new file mode 100644 index 0000000..06848fb --- /dev/null +++ b/spring-boot-demo-swagger/pom.xml @@ -0,0 +1,36 @@ + + + 4.0.0 + + spring-boot-demo-swagger + 0.0.1-SNAPSHOT + jar + + spring-boot-demo-swagger + Demo project for Spring Boot + + + com.xkcoding + spring-boot-demo-parent + 0.0.1-SNAPSHOT + ../spring-boot-demo-parent/pom.xml + + + + 1.5.1.RELEASE + + + + + com.spring4all + spring-boot-starter-swagger + ${swagger.version} + + + + + spring-boot-demo-swagger + + + \ No newline at end of file diff --git a/spring-boot-demo-swagger/src/main/java/com/xkcoding/springbootdemoswagger/SpringBootDemoSwaggerApplication.java b/spring-boot-demo-swagger/src/main/java/com/xkcoding/springbootdemoswagger/SpringBootDemoSwaggerApplication.java new file mode 100644 index 0000000..975bc5c --- /dev/null +++ b/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); + } +} diff --git a/spring-boot-demo-swagger/src/main/java/com/xkcoding/springbootdemoswagger/controller/UserController.java b/spring-boot-demo-swagger/src/main/java/com/xkcoding/springbootdemoswagger/controller/UserController.java new file mode 100644 index 0000000..41024ec --- /dev/null +++ b/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 index(@ApiParam("第几页") @RequestParam(defaultValue = "1") Integer pageNum, @ApiParam("每页的条目数") @RequestParam(defaultValue = "20") Integer pageSize) { + List 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; + } + +} diff --git a/spring-boot-demo-swagger/src/main/java/com/xkcoding/springbootdemoswagger/model/User.java b/spring-boot-demo-swagger/src/main/java/com/xkcoding/springbootdemoswagger/model/User.java new file mode 100644 index 0000000..1d461f4 --- /dev/null +++ b/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; +} diff --git a/spring-boot-demo-swagger/src/main/resources/application.yml b/spring-boot-demo-swagger/src/main/resources/application.yml new file mode 100644 index 0000000..e2bb77e --- /dev/null +++ b/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 \ No newline at end of file diff --git a/spring-boot-demo-swagger/src/test/java/com/xkcoding/springbootdemoswagger/SpringBootDemoSwaggerApplicationTests.java b/spring-boot-demo-swagger/src/test/java/com/xkcoding/springbootdemoswagger/SpringBootDemoSwaggerApplicationTests.java new file mode 100644 index 0000000..e151ffb --- /dev/null +++ b/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() { + } + +}