swagger
主要是为后端服务的接口文档，懒人必备，swagger就是一款让你更好的书写API文档的框架。
其他的框架有阿里爸爸推出 Rap ，感兴趣的可以自己了解一下。
本文主要基于springboot，要先了解下springboot；
开始
Maven
本项目基于maven
springboot pom 中添加
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
| <!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.5.0</version>
</dependency>
<!-- swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.5.0</version>
</dependency>
<dependency>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup-spring-restdocs-ext</artifactId>
<version>2.5.0</version>
<scope>test</scope>
</dependency>
|
启动
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
| package com.example.demo;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@EnableAutoConfiguration
@SpringBootApplication(scanBasePackages = "com.example")
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
}
|
配置
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
| import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket swaggerSpringMvcPlugin() {
return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).build();
}
@Bean
public ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("接口列表 v1.1.0")
.description("接口测试")
.termsOfServiceUrl("http://localhost:8080/")
.contact(new Contact("HUANGJINXING","www.dwxqnswxl.cn","hmm7023@gmail.com"))
.version("1.1.0")
.build();
}
}
|
Controller
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
| package com.example.controller;
import com.example.bean.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.context.request.async.DeferredResult;
import java.util.HashMap;
import java.util.Map;
@Api()
@RestController
@RequestMapping("/demoController")
public class DemoController {
private static final Logger log = LoggerFactory.getLogger(DemoController.class);
public static final String RET_CODE = "retCode";
public static final String RET_MSG = "retMsgo";
@ApiOperation(value = "新增用户", notes = "新增注册")
@PostMapping(value = "/createUser", consumes = MediaType.APPLICATION_JSON_VALUE)
public DeferredResult createUser(@RequestBody User user) {
log.info("createUser:::" , user.toString());
DeferredResult deferredResult = new DeferredResult();
Map map = new HashMap();
map.put(RET_CODE, HttpStatus.OK.value());
map.put(RET_MSG, "新增成功.");
deferredResult.setResult(map);
return deferredResult;
}
@ApiOperation(value = "修改用户", notes = "修改用户")
@PostMapping(value = "/updateUser", consumes = MediaType.APPLICATION_JSON_VALUE)
public DeferredResult updateUser(@RequestBody User user) {
log.info("updateUser:::" , user.toString());
DeferredResult deferredResult = new DeferredResult();
Map map = new HashMap();
map.put(RET_CODE, HttpStatus.OK.value());
map.put(RET_MSG, "修改成功.");
deferredResult.setResult(map);
return deferredResult;
}
@ApiOperation(value = "删除用户", notes = "删除用户")
@ApiImplicitParams({
@ApiImplicitParam(name = "userId", value = "用户标识", required = true, paramType = "query", dataType = "String")
})
@DeleteMapping(value = "/deleteUser")
public DeferredResult deleteUser(@RequestParam("userId") String userId) {
log.info("deleteUser:::" , userId);
DeferredResult deferredResult = new DeferredResult();
Map map = new HashMap();
map.put(RET_CODE, HttpStatus.OK.value());
map.put(RET_MSG, "删除成功.");
deferredResult.setResult(map);
return deferredResult;
}
@ApiOperation(value = "查询用户", notes = "查询用户")
@ApiImplicitParams({
@ApiImplicitParam(name = "userId", value = "用户标识", required = true, paramType = "query", dataType = "String")
})
@GetMapping(value = "/queryUser")
public DeferredResult queryUser(@RequestParam("userId") String userId) {
log.info("queryUser:::" , userId);
DeferredResult deferredResult = new DeferredResult();
Map map = new HashMap();
map.put(RET_CODE, HttpStatus.OK.value());
map.put(RET_MSG, "查询成功.");
map.put("username", "张三.");
map.put("password", "123456");
deferredResult.setResult(map);
return deferredResult;
}
}
|
User类
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
| package com.example.bean;
public class User {
private String username;
private String password;
public String getUsername() {
return username;
}
public void setUsername(String username) {
this.username = username;
}
public String getPassword() {
return password;
}
public void setPassword(String password) {
this.password = password;
}
@Override
public String toString() {
return "User{" +
"username='" + username + '\'' +
", password='" + password + '\'' +
'}';
}
}
|
启动
登陆 http://localhost:8080/swagger-ui.html#/
就可以看到有UI的 接口
swagger的功能不止如此。
效果
