SpringBoot + Swagger + RESTful API实战详解

Java框架

浏览数:93

2019-11-2

SpringBoot简单介绍已经有一篇相关博客,大家可以参考这里,本篇博客主要SpringBoot实战Swagger与RESTful的开发。接下来进入正题:

Jar的相关版本为:
  • Spring Boot 2.0.2
  • Swagger 2.8.0
Swagger简介
  • 对于Swagger的理解,其实就是一个工具,是一个构建API的工具。根据Controller整理出对应的API,当然还可以直接在Swagger-UI上测试。
RESTful简介
  • 上面说了Swagger是构建API的工具,而RESTful 是目前最流行的一种互联网软件架构! REST(Representational State Transfer,表述性状态转移)一词是由 Roy Thomas Fielding 在他 2000 年博士论文中提出的,定义了他对互联网软件的架构原则,如果一个架构符合 REST 原则,则称它为 RESTful 架构。具体介绍,大家可以参考这里
Spring Boot 对 RESTful 的支持

Spring Boot 全面支持开发 RESTful 程序,通过不同的注解来支持前端的请求,除了经常使用的注解外,Spring Boot 还提了一些组合注解。这些组合注解就是我们使用的 @RequestMapping 的简写版.

  • @GetMapping,处理 Get 请求
  • @PostMapping,处理 Post 请求
  • @PutMapping,用于更新资源
  • @DeleteMapping,处理删除请求
@GetMapping(value="/xxx")
等价于
@RequestMapping(value = "/xxx",method = RequestMethod.GET)

@PostMapping(value="/xxx")
等价于
@RequestMapping(value = "/xxx",method = RequestMethod.POST)

.....

Coding

接下来对具体代码进行分析!

1. 相关依赖如下:
<properties>
    <java.version>1.8</java.version>
    <springfox.version>2.8.0</springfox.version>
</properties>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${springfox.version}</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${springfox.version}</version>
</dependency>
2. Swagger配置文件
@Configuration
public class SwaggerConfig {

    @Value("${swagger.enabled}")
    private boolean swaggerEnabled;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).enable(swaggerEnabled).select()
                .apis(RequestHandlerSelectors.basePackage("com.jtcoding.chat")).paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("Simple Chat-Server RESTful APIs")
                .description("Simple Chat-Server Swagger2 RESTful APIs").version("1.0").build();
    }
}
3. 在启动类中加入 @EnableSwagger2 注解
@EnableSwagger2
@SpringBootApplication
public class ChatApplication {

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

}
4. 在application.properties配置文件中,配置swagger的开关
swagger.enabled=true
5. 接下来编写RESTful风格API,下面给一个比较全面一点的API:
@Api(tags = "好友相关")
@RestController
@RequestMapping("/friends")
public class FriendController {

    @Autowired
    private FriendService friendService;

    @ApiOperation(value = "获取好友列表", notes = "获取用户的好友列表")
    @GetMapping("/{userNum}")
    public Result<List<User>> getFriendListByUserNum(@PathVariable Integer userNum) {
        return Result.success(friendService.getFriendListByUserNum(userNum));
    }

    @ApiOperation(value = "搜索好友", notes = "搜索好友")
    @GetMapping("/search/{username}")
    public Result<User> searchUserByUsername(@PathVariable String username) {
        return Result.success(friendService.searchUserByUsername(username));
    }

    @ApiOperation(value = "添加好友", notes = "添加好友")
    @PostMapping("/requests")
    public Result<Boolean> addFriendRequest(@RequestBody FriendRequest friendRequest) {
        return Result.success(friendService.addFriendRequest(friendRequest));
    }

    @ApiOperation(value = "显示好友申请列表", notes = "显示好友申请列表")
    @GetMapping("/requests/{userNum}")
    public Result<List<User>> getUserByFriendReq(@PathVariable Integer userNum) {
        return Result.success(friendService.getUserByFriendReq(userNum));
    }

    @ApiOperation(value = "接受好友申请", notes = "接受好友申请")
    @PutMapping("/requests/accept")
    public Result<User> acceptFriendRequest(@RequestBody FriendRequest friendRequest) {
        return Result.success(friendService.acceptFriendRequest(friendRequest));
    }

    @ApiOperation(value = "拒绝好友申请", notes = "拒绝好友申请")
    @PutMapping("/requests/reject")
    public Result<Boolean> rejectFriendRequest(@RequestBody FriendRequest friendRequest) {
        return Result.success(friendService.rejectFriendRequest(friendRequest));
    }
}
6. 效果如下
  • 整体效果: 具体效果

  • 具体某一个:点击Try it out即可测试

    点击Try it out即可测试

  • 测试效果如下:

    具体详情

总结

具体整合过程已经完成,相关细节方面就是:

  1. 给Swagger加一个开关,可以在配置文件中控制开启或者关闭;
  2. RESTful API规范的设计;
  3. 本文有借鉴过一些文章,如有雷同,这里指明为借鉴。有不对之处,请指出,谢谢!

作者:JasonDev