技术分享 | Spring Boot 集成 Swagger

Swagger UI 允许任何人（无论您是开发团队还是最终用户）都可以可视化 API 资源并与之交互，而无需任何实现逻辑。它是根据您的 OpenAPI（以前称为 Swagger）规范自动生成的，具有可视化文档，可简化后端实现和客户端使用。

为什么使用Swagger

跨语言性，支持 40 多种语言，Swagger 已经慢慢演变成了 OpenAPI 规范；

Swagger UI 呈现出来的是一份可交互式的 API 文档，我们可以直接在文档页面尝试 API 的调用，省去了准备复杂的调用参数的过程；

对于某些没有前端界面 UI 的功能，可以用它来测试接口；

联调方便，如果出问题，直接测试接口，实时检查参数和返回值,就可以快速定位问题。

Swagger快速开始

这里选择 2.9.2 版本。

io.springfox springfox-swagger2 2.9.2 io.springfox springfox-swagger-ui 2.9.2

添加配置类

添加一个 Swagger 配置类，在工程下新建 config 包并添加一个 SwaggerConfig 配置类。 SwaggerConfig.java ```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接口文档界面。 2

测试 展开 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-api/swagger-core/wiki/Annotations-1.5.X#quick-annotation-overview 添加 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 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 list= getData(); UserDto userDto = getUserDto(id, list); return userDto; } /** * 新增用户 * */ @ApiOperation("新增用户") @PostMapping("/users") @ResponseStatus(HttpStatus.CREATED) public Object addUser(@RequestBody UserDto user){ List 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 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 list = getData(); UserDto userDto = getUserDto(id, list); return userDto; } /** * 模拟数据 * */ private List getData(){ List 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 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 Spring Boot

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。