共计 5402 个字符，预计需要花费 14 分钟才能阅读完成。
Swagger UI 容许任何人（无论您是开发团队还是最终用户）都能够可视化 API 资源并与之交互，而无需任何实现逻辑。它是依据您的 OpenAPI（以前称为 Swagger）标准主动生成的，具备可视化文档，可简化后端实现和客户端应用。
为什么应用 Swagger
- 跨语言性，反对 40 多种语言，Swagger 曾经缓缓演变成了 OpenAPI 标准；
- Swagger UI 出现进去的是一份可交互式的 API 文档，咱们能够间接在文档页面尝试 API 的调用，省去了筹备简单的调用参数的过程；
- 对于某些没有前端界面 UI 的性能，能够用它来测试接口；
- 联调不便，如果出问题，间接测试接口，实时查看参数和返回值, 就能够疾速定位问题。
Swagger 疾速开始
这里抉择 2.9.2 版本。
<!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
增加配置类
增加一个 Swagger 配置类，在工程下新建 config 包并增加一个 SwaggerConfig 配置类。SwaggerConfig.java
import com.google.common.collect.Lists;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.schema.ModelRef;
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;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
// 作为 Springfox 框架的次要接口的构建器, 提供正当的默认值和不便的配置办法。@Bean
public Docket docket() {ParameterBuilder builder = new ParameterBuilder();
builder.parameterType("header").name("token")
.description("token 值")
.required(true)
.modelRef(new ModelRef("string")); // 在 swagger 里显示 header
return new Docket(DocumentationType.SWAGGER_2)
.groupName("aitest_interface")
.apiInfo(apiInfo())
.globalOperationParameters(Lists.newArrayList(builder.build()))
.select().paths(PathSelectors.any()).build();}
private ApiInfo apiInfo() {return new ApiInfoBuilder()
.title("aitest-mini 零碎")
.description("aitest-mini 接口文档")
.contact(new Contact("tlibn", "","103@qq.com"))
.version("1.0")
.build();}
}
增加控制器
增加一个控制器，在工程下新建 controller 包并增加一个 Controller 控制器，如果曾经存在 Controller 控制器，则间接启动服务也能够，如上章咱们编写了 HogwartsTestUserController 类，此时间接启动服务即可。关上 swagger 接口文档界面
启动 Spring Boot 服务，关上浏览器，拜访：http://127.0.0.1:8081/swagger-ui.html，进入 swagger 接口文档界面。测试
开展 hogwarts-test-user-controller 的任意接口，输出参数并点击执行，就能够看到接口测试后果了。
Swagger 罕用注解
swagger 通过注解表明该接口会生成文档，包含接口名、申请办法、参数、返回信息的等等。
Api：润饰整个类，形容 Controller 的作用
Api(tags = "霍格沃兹测试学院 - 用户治理模块", hidden = true)
ApiOperation：形容一个类的一个办法，或者说一个接口
ApiOperation("查问用户列表")
ApiParam：单个参数形容
ApiModel：用对象来接管参数
ApiModel(value = "用户登录类", description = "申请类")
ApiProperty：用对象接管参数时，形容对象的一个字段
ApiModelProperty(value="用户 id", example="1",required=true)
ApiResponse：HTTP 响应其中 1 个形容
ApiResponses：HTTP 响应整体形容
ApiIgnore：应用该注解疏忽这个 API
ApiError：产生谬误返回的信息
ApiImplicitParam：一个申请参数
ApiImplicitParams：多个申请参数
更多参见 https://github.com/swagger-ap…
增加 Swagger 罕用注解后的成果
增加 Swagger 罕用注解后的示例代码
HogwartsTestUserController.java
@Api(tags = "霍格沃兹测试学院 - 用户治理模块", hidden = true)
@RestController
@RequestMapping("/api/user")
public class HogwartsTestUserController {
/**
* 查问用户列表，返回一个 JSON 数组
* */
@ApiOperation("查问用户列表")
@GetMapping("/users")
@ResponseStatus(HttpStatus.OK)
public Object getUsers(){List<UserDto> list = getData();
return list;
}
/**
* 查问用户信息，返回一个新建的 JSON 对象
* */
@ApiOperation("查问用户信息")
@GetMapping("/users/{id}")
@ResponseStatus(HttpStatus.OK)
public Object getUser(@PathVariable("id") Long id){if(Objects.isNull(id)){return null;}
List<UserDto> list= getData();
UserDto userDto = getUserDto(id, list);
return userDto;
}
/**
* 新增用户
* */
@ApiOperation("新增用户")
@PostMapping("/users")
@ResponseStatus(HttpStatus.CREATED)
public Object addUser(@RequestBody UserDto user){List<UserDto> list= getData();
list.add(user);// 模仿向列表中减少数据
return user;
}
/**
* 编辑用户
* */
@ApiOperation("编辑用户")
@PutMapping("/users/{id}")
@ResponseStatus(HttpStatus.CREATED)
public Object editUser(@PathVariable("id") Long id,@RequestBody UserDto user){List<UserDto> list = getData();
for (UserDto userDto:list) {if(id.equals(userDto.getId())){
userDto = user;
break;
}
}
return user;
}
/**
* 删除用户
* */
@ApiOperation("删除用户")
@DeleteMapping("/users/{id}")
@ResponseStatus(HttpStatus.NO_CONTENT)
public Object deleteUser(@PathVariable("id") Long id){List<UserDto> list = getData();
UserDto userDto = getUserDto(id, list);
return userDto;
}
/**
* 模仿数据
* */
private List<UserDto> getData(){List<UserDto> list=new ArrayList<>();
UserDto userDto = new UserDto();
userDto.setId(1L);
userDto.setName("admin");
userDto.setPwd("admin");
list.add(userDto);
userDto = new UserDto();
userDto.setId(2L);
userDto.setName("HogwartsTest1");
userDto.setPwd("HogwartsTest1");
list.add(userDto);
userDto = new UserDto();
userDto.setId(3L);
userDto.setName("HogwartsTest2");
userDto.setPwd("HogwartsTest2");
list.add(userDto);
userDto = new UserDto();
userDto.setId(4L);
userDto.setName("HogwartsTest3");
userDto.setPwd("HogwartsTest3");
list.add(userDto);
return list;
}
/**
* 模仿依据 id 查问列表中的数据
* @param id
* @param list
* @return
*/
private UserDto getUserDto(Long id, List<UserDto> list) {
UserDto UserDto = null;
for (UserDto user : list) {if (id.equals(user.getId())) {
UserDto = user;
break;
}
}
return UserDto;
}
}
UserDto.java
@ApiModel(value = "用户登录类", description = "申请类")
public class UserDto {@ApiModelProperty(value="用户 id", example="1",required=true)
private Long id;
@ApiModelProperty(value="用户名称", example="hogwarts1",required=true)
private String name;
@ApiModelProperty(value="用户明码", example="hogwarts2",required=true)
private String pwd;
public Long getId() {return id;}
public void setId(Long id) {this.id = id;}
public String getName() {return name;}
public void setName(String name) {this.name = name;}
public String getPwd() {return pwd;}
public void setPwd(String pwd) {this.pwd = pwd;}
}
Spring Boot 集成 Swagger 就先讲到这里，大家能够照着代码，多练习一下哦~
