Skip to content

Commit 4c3e619

Browse files
author
YunaiV
committed
增加 spring 接口文档示例
1 parent c577bad commit 4c3e619

File tree

10 files changed

+338
-1
lines changed

10 files changed

+338
-1
lines changed

‎lab-24/lab-24-apidoc-swagger-knife4j/pom.xml

+38
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<project xmlns="http://maven.apache.org/POM/4.0.0"
3+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
5+
<parent>
6+
<groupId>org.springframework.boot</groupId>
7+
<artifactId>spring-boot-starter-parent</artifactId>
8+
<version>2.1.3.RELEASE</version>
9+
<relativePath/> <!-- lookup parent from repository -->
10+
</parent>
11+
<modelVersion>4.0.0</modelVersion>
12+
13+
<artifactId>lab-24-apidoc-swagger-knife4j</artifactId>
14+
15+
<dependencies>
16+
<!-- 实现对 Spring MVC 的自动化配置 -->
17+
<dependency>
18+
<groupId>org.springframework.boot</groupId>
19+
<artifactId>spring-boot-starter-web</artifactId>
20+
</dependency>
21+
22+
<!-- 1. swagger-bootstrap-ui 目前改名为 knife4j -->
23+
<!-- 2. 实现 swagger-bootstrap-ui 的自动化配置 -->
24+
<!-- 3. 因为 knife4j-spring 已经引入 Swagger 依赖，所以无需重复引入 -->
25+
<dependency>
26+
<groupId>com.github.xiaoymin</groupId>
27+
<artifactId>knife4j-spring</artifactId>
28+
<version>1.9.6</version>
29+
</dependency>
30+
<dependency>
31+
<groupId>com.github.xiaoymin</groupId>
32+
<artifactId>knife4j-spring-ui</artifactId>
33+
<version>1.9.6</version>
34+
</dependency>
35+
36+
</dependencies>
37+
38+
</project>

‎lab-24/lab-24-apidoc-swagger-knife4j/src/main/java/cn/iocoder/springboot/lab24/apidoc/Application.java

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
package cn.iocoder.springboot.lab24.apidoc;
2+
3+
import org.springframework.boot.SpringApplication;
4+
import org.springframework.boot.autoconfigure.SpringBootApplication;
5+
6+
@SpringBootApplication
7+
public class Application {
8+
9+
public static void main(String[] args) {
10+
SpringApplication.run(Application.class, args);
11+
}
12+
13+
}

‎lab-24/lab-24-apidoc-swagger-knife4j/src/main/java/cn/iocoder/springboot/lab24/apidoc/config/SwaggerConfiguration.java

+43
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
package cn.iocoder.springboot.lab24.apidoc.config;
2+
3+
import org.springframework.context.annotation.Bean;
4+
import org.springframework.context.annotation.Configuration;
5+
import springfox.documentation.builders.ApiInfoBuilder;
6+
import springfox.documentation.builders.PathSelectors;
7+
import springfox.documentation.builders.RequestHandlerSelectors;
8+
import springfox.documentation.service.ApiInfo;
9+
import springfox.documentation.service.Contact;
10+
import springfox.documentation.spi.DocumentationType;
11+
import springfox.documentation.spring.web.plugins.Docket;
12+
import springfox.documentation.swagger2.annotations.EnableSwagger2;
13+
14+
@Configuration
15+
@EnableSwagger2 // 标记项目启用 Swagger API 接口文档
16+
public class SwaggerConfiguration {
17+
18+
@Bean
19+
public Docket createRestApi() {
20+
// 创建 Docket 对象
21+
return new Docket(DocumentationType.SWAGGER_2) // 文档类型，使用 Swagger2
22+
.apiInfo(this.apiInfo()) // 设置 API 信息
23+
// 扫描 Controller 包路径，获得 API 接口
24+
.select()
25+
.apis(RequestHandlerSelectors.basePackage("cn.iocoder.springboot.lab24.apidoc.controller"))
26+
.paths(PathSelectors.any())
27+
// 构建出 Docket 对象
28+
.build();
29+
}
30+
31+
/**
32+
* 创建 API 信息
33+
*/
34+
private ApiInfo apiInfo() {
35+
return new ApiInfoBuilder()
36+
.title("测试接口文档示例")
37+
.description("我是一段描述")
38+
.version("1.0.0") // 版本号
39+
.contact(new Contact("芋艿", "http://www.iocoder.cn", "[email protected]")) // 联系人
40+
.build();
41+
}
42+
43+
}

‎lab-24/lab-24-apidoc-swagger-knife4j/src/main/java/cn/iocoder/springboot/lab24/apidoc/controller/TestController.java

+67
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
package cn.iocoder.springboot.lab24.apidoc.controller;
2+
3+
import cn.iocoder.springboot.lab24.apidoc.dto.UserAddDTO;
4+
import cn.iocoder.springboot.lab24.apidoc.dto.UserUpdateDTO;
5+
import cn.iocoder.springboot.lab24.apidoc.vo.UserVO;
6+
import io.swagger.annotations.ApiImplicitParam;
7+
import io.swagger.annotations.ApiOperation;
8+
import org.springframework.web.bind.annotation.*;
9+
10+
import java.util.ArrayList;
11+
import java.util.List;
12+
import java.util.UUID;
13+
14+
//@RestController
15+
@RequestMapping("/tests")
16+
//@Api(tags = "用户 API 接口")
17+
public class TestController {
18+
19+
@GetMapping("/list")
20+
@ApiOperation(value = "查询用户列表", notes = "目前仅仅是作为测试，所以返回用户全列表")
21+
public List<UserVO> list() {
22+
// 查询列表
23+
List<UserVO> result = new ArrayList<>();
24+
result.add(new UserVO().setId(1).setUsername("yudaoyuanma"));
25+
result.add(new UserVO().setId(2).setUsername("woshiyutou"));
26+
result.add(new UserVO().setId(3).setUsername("chifanshuijiao"));
27+
// 返回列表
28+
return result;
29+
}
30+
31+
@GetMapping("/get")
32+
@ApiOperation("获得指定用户编号的用户")
33+
@ApiImplicitParam(paramType = "query", dataType = "Integer", name = "id", value = "用户编号", required = true, example = "1024")
34+
public UserVO get(@RequestParam("id") Integer id) {
35+
// 查询并返回用户
36+
return new UserVO().setId(id).setUsername(UUID.randomUUID().toString());
37+
}
38+
39+
@PostMapping("add")
40+
@ApiOperation("添加用户")
41+
public Integer add(UserAddDTO addDTO) {
42+
// 插入用户记录，返回编号
43+
Integer returnId = UUID.randomUUID().hashCode();
44+
// 返回用户编号
45+
return returnId;
46+
}
47+
48+
@PostMapping("/update")
49+
@ApiOperation("更新指定用户编号的用户")
50+
public Boolean update(UserUpdateDTO updateDTO) {
51+
// 更新用户记录
52+
Boolean success = true;
53+
// 返回更新是否成功
54+
return success;
55+
}
56+
57+
@PostMapping("/delete")
58+
@ApiOperation("删除指定用户编号的用户")
59+
@ApiImplicitParam(paramType = "query", dataTypeClass = Integer.class, name = "id", value = "用户编号", required = true, example = "1024")
60+
public Boolean delete(@RequestParam("id") Integer id) {
61+
// 删除用户记录
62+
Boolean success = false;
63+
// 返回是否更新成功
64+
return success;
65+
}
66+
67+
}

‎lab-24/lab-24-apidoc-swagger-knife4j/src/main/java/cn/iocoder/springboot/lab24/apidoc/controller/UserController.java

+68
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
package cn.iocoder.springboot.lab24.apidoc.controller;
2+
3+
import cn.iocoder.springboot.lab24.apidoc.dto.UserAddDTO;
4+
import cn.iocoder.springboot.lab24.apidoc.dto.UserUpdateDTO;
5+
import cn.iocoder.springboot.lab24.apidoc.vo.UserVO;
6+
import io.swagger.annotations.Api;
7+
import io.swagger.annotations.ApiImplicitParam;
8+
import io.swagger.annotations.ApiOperation;
9+
import org.springframework.web.bind.annotation.*;
10+
11+
import java.util.ArrayList;
12+
import java.util.List;
13+
import java.util.UUID;
14+
15+
@RestController
16+
@RequestMapping("/users")
17+
@Api(tags = "用户 API 接口")
18+
public class UserController {
19+
20+
@GetMapping("/list")
21+
@ApiOperation(value = "查询用户列表", notes = "目前仅仅是作为测试，所以返回用户全列表")
22+
public List<UserVO> list() {
23+
// 查询列表
24+
List<UserVO> result = new ArrayList<>();
25+
result.add(new UserVO().setId(1).setUsername("yudaoyuanma"));
26+
result.add(new UserVO().setId(2).setUsername("woshiyutou"));
27+
result.add(new UserVO().setId(3).setUsername("chifanshuijiao"));
28+
// 返回列表
29+
return result;
30+
}
31+
32+
@GetMapping("/get")
33+
@ApiOperation("获得指定用户编号的用户")
34+
@ApiImplicitParam(name = "id", value = "用户编号", paramType = "query", dataTypeClass = Integer.class, required = true, example = "1024")
35+
public UserVO get(@RequestParam("id") Integer id) {
36+
// 查询并返回用户
37+
return new UserVO().setId(id).setUsername(UUID.randomUUID().toString());
38+
}
39+
40+
@PostMapping("add")
41+
@ApiOperation("添加用户")
42+
public Integer add(UserAddDTO addDTO) {
43+
// 插入用户记录，返回编号
44+
Integer returnId = UUID.randomUUID().hashCode();
45+
// 返回用户编号
46+
return returnId;
47+
}
48+
49+
@PostMapping("/update")
50+
@ApiOperation("更新指定用户编号的用户")
51+
public Boolean update(UserUpdateDTO updateDTO) {
52+
// 更新用户记录
53+
Boolean success = true;
54+
// 返回更新是否成功
55+
return success;
56+
}
57+
58+
@PostMapping("/delete")
59+
@ApiOperation(value = "删除指定用户编号的用户")
60+
@ApiImplicitParam(name = "id", value = "用户编号", paramType = "query", dataTypeClass = Integer.class, required = true, example = "1024")
61+
public Boolean delete(@RequestParam("id") Integer id) {
62+
// 删除用户记录
63+
Boolean success = false;
64+
// 返回是否更新成功
65+
return success;
66+
}
67+
68+
}

‎lab-24/lab-24-apidoc-swagger-knife4j/src/main/java/cn/iocoder/springboot/lab24/apidoc/dto/UserAddDTO.java

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
package cn.iocoder.springboot.lab24.apidoc.dto;
2+
3+
import io.swagger.annotations.ApiModel;
4+
import io.swagger.annotations.ApiModelProperty;
5+
6+
@ApiModel("用户添加 DTO")
7+
public class UserAddDTO {
8+
9+
@ApiModelProperty(value = "账号", required = true, example = "yudaoyuanma")
10+
private String username;
11+
@ApiModelProperty(value = "密码", required = true, example = "nicai")
12+
private String password;
13+
14+
public String getUsername() {
15+
return username;
16+
}
17+
18+
public UserAddDTO setUsername(String username) {
19+
this.username = username;
20+
return this;
21+
}
22+
23+
public String getPassword() {
24+
return password;
25+
}
26+
27+
public UserAddDTO setPassword(String password) {
28+
this.password = password;
29+
return this;
30+
}
31+
32+
}

‎lab-24/lab-24-apidoc-swagger-knife4j/src/main/java/cn/iocoder/springboot/lab24/apidoc/dto/UserUpdateDTO.java

+43
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
package cn.iocoder.springboot.lab24.apidoc.dto;
2+
3+
import io.swagger.annotations.ApiModel;
4+
import io.swagger.annotations.ApiModelProperty;
5+
6+
@ApiModel("用户更新 DTO")
7+
public class UserUpdateDTO {
8+
9+
@ApiModelProperty(value = "用户编号", required = true, example = "1024")
10+
private Integer id;
11+
@ApiModelProperty(value = "账号", required = true, example = "yudaoyuanma")
12+
private String username;
13+
@ApiModelProperty(value = "密码", required = true, example = "nicai")
14+
private String password;
15+
16+
public Integer getId() {
17+
return id;
18+
}
19+
20+
public UserUpdateDTO setId(Integer id) {
21+
this.id = id;
22+
return this;
23+
}
24+
25+
public String getUsername() {
26+
return username;
27+
}
28+
29+
public UserUpdateDTO setUsername(String username) {
30+
this.username = username;
31+
return this;
32+
}
33+
34+
public String getPassword() {
35+
return password;
36+
}
37+
38+
public UserUpdateDTO setPassword(String password) {
39+
this.password = password;
40+
return this;
41+
}
42+
43+
}

‎lab-24/lab-24-apidoc-swagger-knife4j/src/main/java/cn/iocoder/springboot/lab24/apidoc/vo/UserVO.java

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
package cn.iocoder.springboot.lab24.apidoc.vo;
2+
3+
import io.swagger.annotations.ApiModel;
4+
import io.swagger.annotations.ApiModelProperty;
5+
6+
@ApiModel("用户 VO")
7+
public class UserVO {
8+
9+
@ApiModelProperty(value = "用户编号", required = true, example = "1024")
10+
private Integer id;
11+
@ApiModelProperty(value = "账号", required = true, example = "yudaoyuanma")
12+
private String username;
13+
14+
public Integer getId() {
15+
return id;
16+
}
17+
18+
public UserVO setId(Integer id) {
19+
this.id = id;
20+
return this;
21+
}
22+
23+
public String getUsername() {
24+
return username;
25+
}
26+
27+
public UserVO setUsername(String username) {
28+
this.username = username;
29+
return this;
30+
}
31+
32+
}

‎lab-24/lab-24-apidoc-swagger/src/main/java/cn/iocoder/springboot/lab24/apidoc/controller/UserController.java

+1-1
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ public List<UserVO> list() {
3131

3232
@GetMapping("/get")
3333
@ApiOperation("获得指定用户编号的用户")
34-
@ApiImplicitParam(paramType = "query", dataType = "Integer", name = "id", value = "用户编号", required = true, example = "1024")
34+
@ApiImplicitParam(name = "id", value = "用户编号", paramType = "query", dataTypeClass = Integer.class, required = true, example = "1024")
3535
public UserVO get(@RequestParam("id") Integer id) {
3636
// 查询并返回用户
3737
return new UserVO().setId(id).setUsername(UUID.randomUUID().toString());

‎lab-24/pom.xml

+1
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313
<packaging>pom</packaging>
1414
<modules>
1515
<module>lab-24-apidoc-swagger</module>
16+
<module>lab-24-apidoc-swagger-knife4j</module>
1617
</modules>
1718

1819

0 commit comments

Comments
 (0)