SpringBoot + Swagger + RESTful API实战详解

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. 本文有借鉴过一些文章，如有雷同，这里指明为借鉴。有不对之处，请指出，谢谢！