SpringBoot整合Swagger2实现RESTful风格

SpringBoot整合Swagger2实现RESTful风格

描述	传统请求	方法	RESTful请求	方法
查询	/user/query?name=x	GET	/user?name=x	GET
详情	/user/getInfo?id=1	GET	/user/1	GET
创建	/user/create?name=x	POST	/user	POST
修改	/user/update?name=x&id=1	POST	/user/1	PUT
删除	/user/delete?id=1	GET	/user/1	DELETE

引入依赖

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
            <exclusions>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-models</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.21</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

配置文件SwaggerConfig

@Configuration
@EnableSwagger2
public class SwaggerConfig {

  private ApiInfo apiInfo() {
      return new ApiInfoBuilder()
              .title("user服务") //设置文档的标题
              .description("API 接口文档") // 设置文档的描述
              .version("1.0") // 设置文档的版本信息-> 1.0.0 Version information
              .termsOfServiceUrl("http://www.baidu.com") // 设置文档的License信息->1.3 License information
              .build();
  }
  @Bean
  public Docket createRestApi() {
      return new Docket(DocumentationType.SWAGGER_2)
              .apiInfo(apiInfo())
              .select()
              .apis(RequestHandlerSelectors.basePackage("com.xzh.demo.controller"))
              .paths(PathSelectors.any()) // 可以根据url路径设置哪些请求加入文档，忽略哪些请求
              .build();
  }
}

常用Swagger注解

• @Api：修饰整个类，描述Controller的作用；
• @ApiOperation：描述一个类的一个方法，或者说一个接口；
• @ApiParam：单个参数描述；
• @ApiModel：用对象来接收参数；
• @ApiProperty：用对象接收参数时，描述对象的一个字段；
• @ApiResponse：HTTP响应其中1个描述；
• @ApiResponses：HTTP响应整体描述；
• @ApiIgnore：使用该注解忽略这个API；
• @ApiError ：发生错误返回的信息；
• @ApiImplicitParam：一个请求参数；
• @ApiImplicitParams：多个请求参数。

编写RESTful风格

Spring Boot中包含了一些注解，对应于HTTP协议中的方法：

• @GetMapping对应HTTP中的GET方法；
• @PostMapping对应HTTP中的POST方法；
• @PutMapping对应HTTP中的PUT方法；
• @DeleteMapping对应HTTP中的DELETE方法；
• @PatchMapping对应HTTP中的PATCH方法。
  
  

实现类UserController

  @Controller
@RequestMapping(value = "user")
public class UserController {

    @ApiIgnore //忽视这个api
    @ResponseBody
    @RequestMapping(value ="hello")
    public String hello(){
        return "hello";
    }
    //描述这个接口信息
    @ApiOperation(value = "获取用户信息", notes = "根据用户id获取用户信息")
    @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "Long", paramType = "path")
    @GetMapping("/{id}")
    public @ResponseBody
    User getUserById(@PathVariable(value = "id") Long id) {
        User user = new User();
        user.setId(id);
        user.setName("mrbird");
        user.setAge(25);
        return user;
    }

    @ApiOperation(value = "获取用户列表", notes = "获取用户列表")
    @GetMapping("/list")
    public @ResponseBody
    List<User> getUserList() {
        List<User> list = new ArrayList<>();
        User user1 = new User();
        user1.setId(1l);
        user1.setName("mrbird");
        user1.setAge(20);
        list.add(user1);
        User user2 = new User();
        user2.setId(2l);
        user2.setName("scott");
        user2.setAge(21);
        list.add(user2);
        return list;
    }

    @ApiOperation(value = "新增用户", notes = "根据用户实体创建用户")
    @ApiImplicitParam(name = "user", value = "用户实体", required = true, dataType = "User")
    @PostMapping("/add")
    public @ResponseBody Map<String, Object> addUser(@RequestBody User user) {
        Map<String, Object> map = new HashMap<>();
        map.put("result", "success");
        return map;
    }

    @ApiOperation(value = "删除用户", notes = "根据用户id删除用户")
    @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "Long", paramType = "path")
    @DeleteMapping("/{id}")
    public @ResponseBody Map<String, Object> deleteUser(@PathVariable(value = "id") Long id) {
        Map<String, Object> map = new HashMap<>();
        map.put("result", "success");
        return map;
    }

    @ApiOperation(value = "更新用户", notes = "根据用户id更新用户")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "Long", paramType = "path"),
            @ApiImplicitParam(name = "user", value = "用户实体", required = true, dataType = "User") })
    @PutMapping("/{id}")
    public @ResponseBody Map<String, Object> updateUser(@PathVariable(value = "id") Long id, @RequestBody User user) {
        Map<String, Object> map = new HashMap<>();
        map.put("result", "success");
        return map;
    }

}