diff --git a/spring-boot-demo-swagger-beauty/README.md b/spring-boot-demo-swagger-beauty/README.md new file mode 100644 index 0000000..f0680ea --- /dev/null +++ b/spring-boot-demo-swagger-beauty/README.md @@ -0,0 +1,291 @@ +# spring-boot-demo-swagger-beauty + +> 此 demo 主要演示如何集成第三方的 swagger 来替换原生的 swagger，美化文档样式。本 demo 使用 [swagger-spring-boot-starter](https://github.com/battcn/swagger-spring-boot) 集成。 + +## pom.xml + +```xml + + + 4.0.0 + + spring-boot-demo-swagger-beauty + 1.0.0-SNAPSHOT + jar + + spring-boot-demo-swagger-beauty + Demo project for Spring Boot + + + com.xkcoding + spring-boot-demo + 1.0.0-SNAPSHOT + + + + UTF-8 + UTF-8 + 1.8 + 2.1.2-RELEASE + + + + + org.springframework.boot + spring-boot-starter-web + + + + org.springframework.boot + spring-boot-starter-test + test + + + + com.battcn + swagger-spring-boot-starter + ${battcn.swagger.version} + + + + org.projectlombok + lombok + true + + + + + spring-boot-demo-swagger-beauty + + + org.springframework.boot + spring-boot-maven-plugin + + + + + +``` + +## application.yml + +```yaml +server: + port: 8080 + servlet: + context-path: /demo +spring: + swagger: + enabled: true + title: spring-boot-demo + description: 这是一个简单的 Swagger API 演示 + version: 1.0.0-SNAPSHOT + contact: + name: Yangkai.Shen + email: 237497819@qq.com + url: http://xkcoding.com + # swagger扫描的基础包，默认：全扫描 + # base-package: + # 需要处理的基础URL规则，默认：/** + # base-path: + # 需要排除的URL规则，默认：空 + # exclude-path: + security: + # 是否启用 swagger 登录验证 + filter-plugin: true + username: xkcoding + password: 123456 + global-response-messages: + GET[0]: + code: 400 + message: Bad Request，一般为请求参数不对 + GET[1]: + code: 404 + message: NOT FOUND，一般为请求路径不对 + GET[2]: + code: 500 + message: ERROR，一般为程序内部错误 + POST[0]: + code: 400 + message: Bad Request，一般为请求参数不对 + POST[1]: + code: 404 + message: NOT FOUND，一般为请求路径不对 + POST[2]: + code: 500 + message: ERROR，一般为程序内部错误 +``` + +## ApiResponse.java + +```java +/** + *

+ * 通用API接口返回 + *

+ * + * @package: com.xkcoding.swagger.beauty.common + * @description: 通用API接口返回 + * @author: yangkai.shen + * @date: Created in 2018-11-28 14:18 + * @copyright: Copyright (c) 2018 + * @version: V1.0 + * @modified: yangkai.shen + */ +@Data +@Builder +@NoArgsConstructor +@AllArgsConstructor +@ApiModel(value = "通用PI接口返回", description = "Common Api Response") +public class ApiResponse implements Serializable { + private static final long serialVersionUID = -8987146499044811408L; + /** + * 通用返回状态 + */ + @ApiModelProperty(value = "通用返回状态", required = true) + private Integer code; + /** + * 通用返回信息 + */ + @ApiModelProperty(value = "通用返回信息", required = true) + private String message; + /** + * 通用返回数据 + */ + @ApiModelProperty(value = "通用返回数据", required = true) + private T data; +} +``` + +## User.java + +```java +/** + *

+ * 用户实体 + *

+ * + * @package: com.xkcoding.swagger.beauty.entity + * @description: 用户实体 + * @author: yangkai.shen + * @date: Created in 2018-11-28 14:13 + * @copyright: Copyright (c) 2018 + * @version: V1.0 + * @modified: yangkai.shen + */ +@Data +@NoArgsConstructor +@AllArgsConstructor +@ApiModel(value = "用户实体", description = "User Entity") +public class User implements Serializable { + private static final long serialVersionUID = 5057954049311281252L; + /** + * 主键id + */ + @ApiModelProperty(value = "主键id", required = true) + private Integer id; + /** + * 用户名 + */ + @ApiModelProperty(value = "用户名", required = true) + private String name; + /** + * 工作岗位 + */ + @ApiModelProperty(value = "工作岗位", required = true) + private String job; +} +``` + +## UserController.java + +```java +/** + *

+ * User Controller + *

+ * + * @package: com.xkcoding.swagger.beauty.controller + * @description: User Controller + * @author: yangkai.shen + * @date: Created in 2018-11-28 14:25 + * @copyright: Copyright (c) 2018 + * @version: V1.0 + * @modified: yangkai.shen + */ +@RestController +@RequestMapping("/user") +@Api(tags = "1.0.0-SNAPSHOT", description = "用户管理", value = "用户管理") +@Slf4j +public class UserController { + @GetMapping + @ApiOperation(value = "条件查询（DONE）", notes = "备注") + @ApiImplicitParams({@ApiImplicitParam(name = "username", value = "用户名", dataType = DataType.STRING, paramType = ParamType.QUERY, defaultValue = "xxx")}) + public ApiResponse getByUserName(String username) { + log.info("多个参数用 @ApiImplicitParams"); + return ApiResponse.builder().code(200).message("操作成功").data(new User(1, username, "JAVA")).build(); + } + + @GetMapping("/{id}") + @ApiOperation(value = "主键查询（DONE）", notes = "备注") + @ApiImplicitParams({@ApiImplicitParam(name = "id", value = "用户编号", dataType = DataType.INT, paramType = ParamType.PATH)}) + public ApiResponse get(@PathVariable Integer id) { + log.info("单个参数用 @ApiImplicitParam"); + return ApiResponse.builder().code(200).message("操作成功").data(new User(id, "u1", "p1")).build(); + } + + @DeleteMapping("/{id}") + @ApiOperation(value = "删除用户（DONE）", notes = "备注") + @ApiImplicitParam(name = "id", value = "用户编号", dataType = DataType.INT, paramType = ParamType.PATH) + public void delete(@PathVariable Integer id) { + log.info("单个参数用 ApiImplicitParam"); + } + + @PostMapping + @ApiOperation(value = "添加用户（DONE）") + public User post(@RequestBody User user) { + log.info("如果是 POST PUT 这种带 @RequestBody 的可以不用写 @ApiImplicitParam"); + return user; + } + + @PostMapping("/multipar") + @ApiOperation(value = "添加用户（DONE）") + public List multipar(@RequestBody List user) { + log.info("如果是 POST PUT 这种带 @RequestBody 的可以不用写 @ApiImplicitParam"); + + return user; + } + + @PostMapping("/array") + @ApiOperation(value = "添加用户（DONE）") + public User[] array(@RequestBody User[] user) { + log.info("如果是 POST PUT 这种带 @RequestBody 的可以不用写 @ApiImplicitParam"); + return user; + } + + @PutMapping("/{id}") + @ApiOperation(value = "修改用户（DONE）") + public void put(@PathVariable Long id, @RequestBody User user) { + log.info("如果你不想写 @ApiImplicitParam 那么 swagger 也会使用默认的参数名作为描述信息 "); + } + + @PostMapping("/{id}/file") + @ApiOperation(value = "文件上传（DONE）") + public String file(@PathVariable Long id, @RequestParam("file") MultipartFile file) { + log.info(file.getContentType()); + log.info(file.getName()); + log.info(file.getOriginalFilename()); + return file.getOriginalFilename(); + } +} +``` + +## 参考 + +- https://github.com/battcn/swagger-spring-boot/blob/master/README.md +- 几款比较好看的swagger-ui，具体使用方法参见各个依赖的官方文档： + - [battcn](https://github.com/battcn) 的 [swagger-spring-boot-starter](https://github.com/battcn/swagger-spring-boot) 文档：https://github.com/battcn/swagger-spring-boot/blob/master/README.md + - [ swagger-ui-layer](https://gitee.com/caspar-chen/Swagger-UI-layer) 文档：https://gitee.com/caspar-chen/Swagger-UI-layer#%E5%A6%82%E4%BD%95%E4%BD%BF%E7%94%A8 + - [swagger-bootstrap-ui](https://gitee.com/xiaoym/swagger-bootstrap-ui) 文档：https://gitee.com/xiaoym/swagger-bootstrap-ui#%E4%BD%BF%E7%94%A8%E8%AF%B4%E6%98%8E + - [swagger-ui-themes](https://github.com/ostranme/swagger-ui-themes) 文档：https://github.com/ostranme/swagger-ui-themes#getting-started \ No newline at end of file diff --git a/spring-boot-demo-swagger-beauty/src/main/java/com/xkcoding/swagger/beauty/common/ApiResponse.java b/spring-boot-demo-swagger-beauty/src/main/java/com/xkcoding/swagger/beauty/common/ApiResponse.java new file mode 100644 index 0000000..43ce02a --- /dev/null +++ b/spring-boot-demo-swagger-beauty/src/main/java/com/xkcoding/swagger/beauty/common/ApiResponse.java @@ -0,0 +1,47 @@ +package com.xkcoding.swagger.beauty.common; + +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; +import lombok.AllArgsConstructor; +import lombok.Builder; +import lombok.Data; +import lombok.NoArgsConstructor; + +import java.io.Serializable; + +/** + *

+ * 通用API接口返回 + *

+ * + * @package: com.xkcoding.swagger.beauty.common + * @description: 通用API接口返回 + * @author: yangkai.shen + * @date: Created in 2018-11-28 14:18 + * @copyright: Copyright (c) 2018 + * @version: V1.0 + * @modified: yangkai.shen + */ +@Data +@Builder +@NoArgsConstructor +@AllArgsConstructor +@ApiModel(value = "通用PI接口返回", description = "Common Api Response") +public class ApiResponse implements Serializable { + private static final long serialVersionUID = -8987146499044811408L; + /** + * 通用返回状态 + */ + @ApiModelProperty(value = "通用返回状态", required = true) + private Integer code; + /** + * 通用返回信息 + */ + @ApiModelProperty(value = "通用返回信息", required = true) + private String message; + /** + * 通用返回数据 + */ + @ApiModelProperty(value = "通用返回数据", required = true) + private T data; +} diff --git a/spring-boot-demo-swagger-beauty/src/main/java/com/xkcoding/swagger/beauty/controller/UserController.java b/spring-boot-demo-swagger-beauty/src/main/java/com/xkcoding/swagger/beauty/controller/UserController.java new file mode 100644 index 0000000..f8667d1 --- /dev/null +++ b/spring-boot-demo-swagger-beauty/src/main/java/com/xkcoding/swagger/beauty/controller/UserController.java @@ -0,0 +1,94 @@ +package com.xkcoding.swagger.beauty.controller; + +import com.battcn.boot.swagger.model.DataType; +import com.battcn.boot.swagger.model.ParamType; +import com.xkcoding.swagger.beauty.common.ApiResponse; +import com.xkcoding.swagger.beauty.entity.User; +import io.swagger.annotations.Api; +import io.swagger.annotations.ApiImplicitParam; +import io.swagger.annotations.ApiImplicitParams; +import io.swagger.annotations.ApiOperation; +import lombok.extern.slf4j.Slf4j; +import org.springframework.web.bind.annotation.*; +import org.springframework.web.multipart.MultipartFile; + +import java.util.List; + +/** + *

+ * User Controller + *

+ * + * @package: com.xkcoding.swagger.beauty.controller + * @description: User Controller + * @author: yangkai.shen + * @date: Created in 2018-11-28 14:25 + * @copyright: Copyright (c) 2018 + * @version: V1.0 + * @modified: yangkai.shen + */ +@RestController +@RequestMapping("/user") +@Api(tags = "1.0.0-SNAPSHOT", description = "用户管理", value = "用户管理") +@Slf4j +public class UserController { + @GetMapping + @ApiOperation(value = "条件查询（DONE）", notes = "备注") + @ApiImplicitParams({@ApiImplicitParam(name = "username", value = "用户名", dataType = DataType.STRING, paramType = ParamType.QUERY, defaultValue = "xxx")}) + public ApiResponse getByUserName(String username) { + log.info("多个参数用 @ApiImplicitParams"); + return ApiResponse.builder().code(200).message("操作成功").data(new User(1, username, "JAVA")).build(); + } + + @GetMapping("/{id}") + @ApiOperation(value = "主键查询（DONE）", notes = "备注") + @ApiImplicitParams({@ApiImplicitParam(name = "id", value = "用户编号", dataType = DataType.INT, paramType = ParamType.PATH)}) + public ApiResponse get(@PathVariable Integer id) { + log.info("单个参数用 @ApiImplicitParam"); + return ApiResponse.builder().code(200).message("操作成功").data(new User(id, "u1", "p1")).build(); + } + + @DeleteMapping("/{id}") + @ApiOperation(value = "删除用户（DONE）", notes = "备注") + @ApiImplicitParam(name = "id", value = "用户编号", dataType = DataType.INT, paramType = ParamType.PATH) + public void delete(@PathVariable Integer id) { + log.info("单个参数用 ApiImplicitParam"); + } + + @PostMapping + @ApiOperation(value = "添加用户（DONE）") + public User post(@RequestBody User user) { + log.info("如果是 POST PUT 这种带 @RequestBody 的可以不用写 @ApiImplicitParam"); + return user; + } + + @PostMapping("/multipar") + @ApiOperation(value = "添加用户（DONE）") + public List multipar(@RequestBody List user) { + log.info("如果是 POST PUT 这种带 @RequestBody 的可以不用写 @ApiImplicitParam"); + + return user; + } + + @PostMapping("/array") + @ApiOperation(value = "添加用户（DONE）") + public User[] array(@RequestBody User[] user) { + log.info("如果是 POST PUT 这种带 @RequestBody 的可以不用写 @ApiImplicitParam"); + return user; + } + + @PutMapping("/{id}") + @ApiOperation(value = "修改用户（DONE）") + public void put(@PathVariable Long id, @RequestBody User user) { + log.info("如果你不想写 @ApiImplicitParam 那么 swagger 也会使用默认的参数名作为描述信息 "); + } + + @PostMapping("/{id}/file") + @ApiOperation(value = "文件上传（DONE）") + public String file(@PathVariable Long id, @RequestParam("file") MultipartFile file) { + log.info(file.getContentType()); + log.info(file.getName()); + log.info(file.getOriginalFilename()); + return file.getOriginalFilename(); + } +} diff --git a/spring-boot-demo-swagger-beauty/src/main/java/com/xkcoding/swagger/beauty/entity/User.java b/spring-boot-demo-swagger-beauty/src/main/java/com/xkcoding/swagger/beauty/entity/User.java new file mode 100644 index 0000000..758afad --- /dev/null +++ b/spring-boot-demo-swagger-beauty/src/main/java/com/xkcoding/swagger/beauty/entity/User.java @@ -0,0 +1,45 @@ +package com.xkcoding.swagger.beauty.entity; + +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; +import lombok.AllArgsConstructor; +import lombok.Data; +import lombok.NoArgsConstructor; + +import java.io.Serializable; + +/** + *

+ * 用户实体 + *

+ * + * @package: com.xkcoding.swagger.beauty.entity + * @description: 用户实体 + * @author: yangkai.shen + * @date: Created in 2018-11-28 14:13 + * @copyright: Copyright (c) 2018 + * @version: V1.0 + * @modified: yangkai.shen + */ +@Data +@NoArgsConstructor +@AllArgsConstructor +@ApiModel(value = "用户实体", description = "User Entity") +public class User implements Serializable { + private static final long serialVersionUID = 5057954049311281252L; + /** + * 主键id + */ + @ApiModelProperty(value = "主键id", required = true) + private Integer id; + /** + * 用户名 + */ + @ApiModelProperty(value = "用户名", required = true) + private String name; + /** + * 工作岗位 + */ + @ApiModelProperty(value = "工作岗位", required = true) + private String job; +}