柒索

一个头脑聪明,五肢发达的男人。

0%

Spring Boot - 使用Swagger2构建Rest服务

简介:

Swagger:

Swagger(Swagger 2)是用于描述和记录REST API的规范。它指定了REST Web服务的格式,包括URL,资源,方法等。Swagger将从应用程序代码生成文档并处理渲染部分。

Springfox提供了两个依赖关系来生成API Doc和Swagger UI。如果不希望将Swagger UI集成到您的API级别中,则无需添加Swagger UI依赖项。

Restful:

Restful是一种软件架构风格、设计风格,而不是标准,只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁,更有层次,更易于实现缓存等机制。

Restful使用HTTP,URI,XML,JSON,HTML等广泛流行的标准和协议;轻量级,跨平台,跨语言的架构设计;

URI: /资源名称/资源标识 HTTP请求方式区分对资源CRUD操作

普通CRUD(uri来区分操作) RestfulCRUD
查询 getEmp emp—GET
添加 addEmp?xxx emp—POST
修改 updateEmp?id=xxx&xxx=xx emp/{id}—PUT
删除 deleteEmp?id=1 emp/{id}—DELETE

配置:

Swagger2:

要在项目中使用Swagger2,则需要添加以下依赖:

1
2
3
4
5
6
7
8
9
10
11
 <!--Swagger 相关依赖-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>

还需要在SpringBoot的启动类上添加注解:

1
2
3
4
5
6
7
8
@EnableSwagger2
@SpringBootApplication
public class SpringbootRestApplication {

public static void main(String[] args) {
SpringApplication.run(SpringbootRestApplication.class, args);
}
}

开发:

pom.xml:

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
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>

<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-devtools</artifactId>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<optional>true</optional>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>com.jayway.jsonpath</groupId>
<artifactId>json-path</artifactId>
<scope>test</scope>
</dependency>
<!--Swagger 相关依赖-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>
</dependencies>

greeting:

1
2
3
4
5
@Data
public class Greeting {
private final long id;
private final String content;
}

GreetingController:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
@Api(value = "GreetingController",tags = "Controller")
@RestController
public class GreetingController {

private static final String template = "Hello, %s!";
private final AtomicLong counter = new AtomicLong();


@ApiOperation(value = "测试Rest",notes = "Rest")
@ApiImplicitParams({
@ApiImplicitParam(paramType ="query",name ="name",dataType = "String",required = true,value = "Rest",defaultValue = "Rest")
})
@ApiResponses({
@ApiResponse(code = 400,message = "请求参数填写错误"),
@ApiResponse(code = 404,message = "请求路径错误")
})
@RequestMapping("/greeting")
public Greeting greeting(@RequestParam(value="name", defaultValue="Rest") String name) {
return new Greeting(counter.incrementAndGet(),
String.format(template, name));
}
}

Swagger注解的使用:

- **@Api()**用于类;  表示标识这个类是swagger的资源 
- **@ApiOperation()**用于方法;  表示一个http请求的操作
- **@ApiParam()**用于方法,参数,字段说明;  表示对参数的添加元数据(说明或是否必填等) 
- **@ApiModel()**用于类  表示对类进行说明,用于参数用实体类接收
- **@ApiModelProperty()**用于方法,字段  表示对model属性的说明或者数据操作更改
- **@ApiIgnore()**用于类,方法,方法参数  表示这个方法或者类被忽略 
@ApiImplicitParam() 用于方法  表示单独的请求参数 
@ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam