1.在POM.xml中引入相关的Jar依赖
<!-- swagger2 ui jar -->
<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>
<!-- swagger2 ui jar -->
2. 开启Springboot 对swagger2的支持
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@SpringBootApplication // 组件扫描
@EnableSwagger2 //开启swagger2的支持
public class SwaggerExampleApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggerExampleApplication.class, args);
}
}
3.定义UserController Restful Api
package com.swagger.controller;
import com.swagger.bean.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;
import javax.validation.Valid;
import java.util.ArrayList;
import java.util.List;
/**
* Created by daizhao.
* User: tony
* Date: 2018-3-21
* Time: 13:54
* info:
*/
@RestController
@RequestMapping("/user")
@Api("UserController API")
public class UserController {
@ApiOperation("创建用户")
@PostMapping("/users")
public User create(@RequestBody @Valid User user) {
return user;
}
@ApiOperation("用户详情")
@GetMapping("/users/{id}")
public User findById(@PathVariable Long id) {
return new User("bbb", 21, "上海", "aaa@bbb.com");
}
@ApiOperation("用户列表")
@GetMapping("/users")
public List<User> list(@ApiParam("查看第几页") @RequestParam int pageIndex,
@ApiParam("每页多少条") @RequestParam int pageSize) {
List<User> result = new ArrayList<>();
result.add(new User("aaa", 50, "北京", "aaa@ccc.com"));
result.add(new User("bbb", 21, "广州", "aaa@ddd.com"));
return result;
}
//@ApiIgnore
@ApiOperation("删除列表")
@DeleteMapping("/users/{id}")
public String deleteById(@PathVariable Long id) {
return "delete user : " + id;
}
}
相关的User类
package com.swagger.bean;
/**
* Created by daizhao.
* User: tony
* Date: 2018-3-21
* Time: 10:56
* info:
*/
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import javax.validation.constraints.*;
@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel("用户基本信息")
public class User {
@ApiModelProperty("姓名")
@Size(max = 20)
private String name;
@ApiModelProperty("年龄")
@Max(150)
@Min(1)
private Integer age;
@NotNull
private String address;
@Pattern(regexp = "^[a-zA-Z0-9_-]+@[a-zA-Z0-9_-]+(\\.[a-zA-Z0-9_-]+)+$")
private String email;
}
4.说明:
@Api:用在类上,说明该类的作用
@ApiOperation:用在方法上,说明方法的作用
@ApiImplicitParams:用在方法上包含一组参数说明
@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
paramType:参数放在哪个地方
header-->请求参数的获取:@RequestHeader
query-->请求参数的获取:@RequestParam
path(用于restful接口)-->请求参数的获取:@PathVariable
body(不常用)
form(不常用)
name:参数名
dataType:参数类型
required:参数是否必须传
value:参数的意思
defaultValue:参数的默认值
@ApiResponses:用于表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
code:数字,例如400
message:信息,例如"请求参数没填好"
response:抛出异常的类
@ApiModel:描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候)
@ApiModelProperty:描述一个model的属性
5.启动服务 ,直接访问 “http://localhost:8080/swagger-ui.html”即可(这个是带Ui界面的)
还有一个地址是:http://localhost:8080/v2/api-docs