+ * Swagger2 配置 + *
+ * + * @package: com.xkcoding.swagger.config + * @description: Swagger2 配置 + * @author: yangkai.shen + * @date: Created in 2018-11-29 11:14 + * @copyright: Copyright (c) 2018 + * @version: V1.0 + * @modified: yangkai.shen + */ +@Configuration +@EnableSwagger2 +public class Swagger2Config { + + @Bean + public Docket createRestApi() { + return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()) + .select() + .apis(RequestHandlerSelectors.basePackage("com.xkcoding.swagger.controller")) + .paths(PathSelectors.any()) + .build(); + } + + private ApiInfo apiInfo() { + return new ApiInfoBuilder().title("spring-boot-demo") + .description("这是一个简单的 Swagger API 演示") + .contact(new Contact("Yangkai.Shen", "http://xkcoding.com", "237497819@qq.com")) + .version("1.0.0-SNAPSHOT") + .build(); + } + +} +``` + +## UserController.java + +> 主要演示API层的注解。 + +```java +/** + *+ * User Controller + *
+ * + * @package: com.xkcoding.swagger.controller + * @description: User Controller + * @author: yangkai.shen + * @date: Created in 2018-11-29 11:30 + * @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+ * 通用API接口返回 + *
+ * + * @package: com.xkcoding.swagger.common + * @description: 通用API接口返回 + * @author: yangkai.shen + * @date: Created in 2018-11-29 11:30 + * @copyright: Copyright (c) 2018 + * @version: V1.0 + * @modified: yangkai.shen + */ +@Data +@Builder +@NoArgsConstructor +@AllArgsConstructor +@ApiModel(value = "通用PI接口返回", description = "Common Api Response") +public class ApiResponse+ * 启动器 + *
+ * + * @package: com.xkcoding.swagger + * @description: 启动器 + * @author: yangkai.shen + * @date: Created in 2018-11-29 13:25 + * @copyright: Copyright (c) 2018 + * @version: V1.0 + * @modified: yangkai.shen + */ @SpringBootApplication public class SpringBootDemoSwaggerApplication { diff --git a/spring-boot-demo-swagger/src/main/java/com/xkcoding/swagger/common/ApiResponse.java b/spring-boot-demo-swagger/src/main/java/com/xkcoding/swagger/common/ApiResponse.java new file mode 100644 index 0000000..523a8b6 --- /dev/null +++ b/spring-boot-demo-swagger/src/main/java/com/xkcoding/swagger/common/ApiResponse.java @@ -0,0 +1,47 @@ +package com.xkcoding.swagger.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.common + * @description: 通用API接口返回 + * @author: yangkai.shen + * @date: Created in 2018-11-29 11:30 + * @copyright: Copyright (c) 2018 + * @version: V1.0 + * @modified: yangkai.shen + */ +@Data +@Builder +@NoArgsConstructor +@AllArgsConstructor +@ApiModel(value = "通用PI接口返回", description = "Common Api Response") +public class ApiResponse+ * 方便在 @ApiImplicitParam 的 dataType 属性使用 + *
+ * + * @package: com.xkcoding.swagger.common + * @description: 方便在 @ApiImplicitParam 的 dataType 属性使用 + * @author: yangkai.shen + * @date: Created in 2018-11-29 13:23 + * @copyright: Copyright (c) 2018 + * @version: V1.0 + * @modified: yangkai.shen + */ +public final class DataType { + + public final static String STRING = "String"; + public final static String INT = "int"; + public final static String LONG = "long"; + public final static String DOUBLE = "double"; + public final static String FLOAT = "float"; + public final static String BYTE = "byte"; + public final static String BOOLEAN = "boolean"; + public final static String ARRAY = "array"; + public final static String BINARY = "binary"; + public final static String DATETIME = "dateTime"; + public final static String PASSWORD = "password"; + +} \ No newline at end of file diff --git a/spring-boot-demo-swagger/src/main/java/com/xkcoding/swagger/common/ParamType.java b/spring-boot-demo-swagger/src/main/java/com/xkcoding/swagger/common/ParamType.java new file mode 100644 index 0000000..438cea8 --- /dev/null +++ b/spring-boot-demo-swagger/src/main/java/com/xkcoding/swagger/common/ParamType.java @@ -0,0 +1,24 @@ +package com.xkcoding.swagger.common; + +/** + *+ * 方便在 @ApiImplicitParam 的 paramType 属性使用 + *
+ * + * @package: com.xkcoding.swagger.common + * @description: 方便在 @ApiImplicitParam 的 paramType 属性使用 + * @author: yangkai.shen + * @date: Created in 2018-11-29 13:24 + * @copyright: Copyright (c) 2018 + * @version: V1.0 + * @modified: yangkai.shen + */ +public final class ParamType { + + public final static String QUERY = "query"; + public final static String HEADER = "header"; + public final static String PATH = "path"; + public final static String BODY = "body"; + public final static String FORM = "form"; + +} \ No newline at end of file diff --git a/spring-boot-demo-swagger/src/main/java/com/xkcoding/swagger/config/Swagger2Config.java b/spring-boot-demo-swagger/src/main/java/com/xkcoding/swagger/config/Swagger2Config.java new file mode 100644 index 0000000..04d0924 --- /dev/null +++ b/spring-boot-demo-swagger/src/main/java/com/xkcoding/swagger/config/Swagger2Config.java @@ -0,0 +1,48 @@ +package com.xkcoding.swagger.config; + +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; +import springfox.documentation.builders.ApiInfoBuilder; +import springfox.documentation.builders.PathSelectors; +import springfox.documentation.builders.RequestHandlerSelectors; +import springfox.documentation.service.ApiInfo; +import springfox.documentation.service.Contact; +import springfox.documentation.spi.DocumentationType; +import springfox.documentation.spring.web.plugins.Docket; +import springfox.documentation.swagger2.annotations.EnableSwagger2; + +/** + *+ * Swagger2 配置 + *
+ * + * @package: com.xkcoding.swagger.config + * @description: Swagger2 配置 + * @author: yangkai.shen + * @date: Created in 2018-11-29 11:14 + * @copyright: Copyright (c) 2018 + * @version: V1.0 + * @modified: yangkai.shen + */ +@Configuration +@EnableSwagger2 +public class Swagger2Config { + + @Bean + public Docket createRestApi() { + return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()) + .select() + .apis(RequestHandlerSelectors.basePackage("com.xkcoding.swagger.controller")) + .paths(PathSelectors.any()) + .build(); + } + + private ApiInfo apiInfo() { + return new ApiInfoBuilder().title("spring-boot-demo") + .description("这是一个简单的 Swagger API 演示") + .contact(new Contact("Yangkai.Shen", "http://xkcoding.com", "237497819@qq.com")) + .version("1.0.0-SNAPSHOT") + .build(); + } + +} \ No newline at end of file diff --git a/spring-boot-demo-swagger/src/main/java/com/xkcoding/swagger/controller/UserController.java b/spring-boot-demo-swagger/src/main/java/com/xkcoding/swagger/controller/UserController.java new file mode 100644 index 0000000..db6cd11 --- /dev/null +++ b/spring-boot-demo-swagger/src/main/java/com/xkcoding/swagger/controller/UserController.java @@ -0,0 +1,100 @@ +package com.xkcoding.swagger.controller; + +import com.xkcoding.swagger.common.ApiResponse; +import com.xkcoding.swagger.common.DataType; +import com.xkcoding.swagger.common.ParamType; +import com.xkcoding.swagger.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.controller + * @description: User Controller + * @author: yangkai.shen + * @date: Created in 2018-11-29 11:30 + * @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+ * 用户实体 + *
+ * + * @package: com.xkcoding.swagger.entity + * @description: 用户实体 + * @author: yangkai.shen + * @date: Created in 2018-11-29 11:31 + * @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; +} diff --git a/spring-boot-demo-swagger/src/main/resources/application.properties b/spring-boot-demo-swagger/src/main/resources/application.properties deleted file mode 100644 index e69de29..0000000 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..a02fbde --- /dev/null +++ b/spring-boot-demo-swagger/src/main/resources/application.yml @@ -0,0 +1,4 @@ +server: + port: 8080 + servlet: + context-path: /demo \ No newline at end of file