SpringBoot整合Swagger2--搭建RestfulAPI在线文档

阳光穿透心脏的1/2处 2021-08-29 14:43 385阅读 0赞

#### Swagger ####

Swagger,中文“拽"的意思，它是一个功能强大的在线API文档的框架，目前它的版本为2.x,所以称为Swagger2。

Swagger2提供了在线文档的查阅和测试功能。利用Swagger2很容易构建RESTful风格的API，在Spring Boot中集成Swagger2，需要以下几个步骤。

##### 1. 依赖 #####

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

##### 2. 配置Swagger2 #####

在配置类中需要注入一个Docket的Bean，该Bean包含了apiInfo，即基本API文档的描述信息，以及包扫描的基本包名等信息：

@Configuration
    @EnableSwagger2
    public class Swagger2 { 
    
        @Bean
        public Docket createRestApi() { 
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("pers.zhang.sc_book.controller"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo() { 
            return new ApiInfoBuilder()
                    .title("springboot利用swagger构建api文档")
                    .description("简单优雅的restful风格,http://www.baidu.com")
                    .termsOfServiceUrl("http://www.baidu.com")
                    .version("1.0")
                    .build();
        }
    }

##### 3. 写生成文档的注解 #####

Swagger2通过注解来生成API接口文档，文档信息包括接口名、请求方法、参数、返回信息等。通常情况下用于生成在线API文档，以下的注解能够满足基本需求，注解及其描述如下。

*  `@Api`: 修饰整个类，用于描述Controller类。
 *  `@ApiOperation`: 描述类的方法，或者说一个接口。
 *  `@ApiParam`: 单个参数描述。
 *  `@ApiModel`: 用对象来接收参数。
 *  `@ApiProperty`: 用对象接收参数时，描述对象的一一个字段。
 *  `@ApiResponse`: HTTP响应的一个描述。
 *  `@ApiResponses`: HTTP 响应的整体描述。
 *  `@Apilgnore`: 使用该注解，表示Swagger2忽略这个API。
 *  `@ApiError` :发生错误返回的信息。
 *  `@ApiParamImplicit`: 一个请求参数。
 *  `@ApiParamsImplicit`: 多个请求参数。

##### 4. Controller代码 #####

在Web层通过Get、Post、Delete、Put这4种Http方法，构建一组以资源为中心的RESTful风格的API接口：

@RestController
    @RequestMapping("/user")
    public class UserController { 
    
        @Autowired
        UserService userService;
    
        @ApiOperation(value = "用户列表", notes = "用户列表")
        @GetMapping("")
        public List<User> getUsers() { 
            return userService.findAll();
        }
    
        @ApiOperation(value = "创建用户", notes = "创建用户")
        @PostMapping("")
        public User postUser(@RequestBody User user) { 
            return userService.saveUser(user);
        }
    
        @ApiOperation(value = "获取用户详细信息", notes = "根据url的id获取详细信息")
        @GetMapping("/{id}")
        public User getUser(@PathVariable Long id) { 
            return userService.findUserById(id);
        }
    
        @ApiOperation(value = "更新信息", notes = "根据url的id来指定更新用户信息")
        @PutMapping("/{id}")
        public User putUser(@PathVariable Long id, @RequestBody User user) { 
            User u = new User();
            u.setUsername(user.getUsername());
            u.setPassword(user.getPassword());
            u.setId(id);
            return userService.updateUser(u);
        }
    
        @ApiOperation(value = "删除用户", notes = "根据url的id来指定删除用户")
        @DeleteMapping("/{id}")
        public String deleteUser(@PathVariable Long id) { 
            userService.deleteUser(id);
            return "success";
        }
    
        @ApiIgnore//使用该注解则忽略这个API
        @RequestMapping(value = "/hi", method = RequestMethod.GET)
        public String jsonTest() { 
            return "hi you!";
        }
    }

访问：`项目路径/swagger-ui.html`查看

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2NvbGRfX19wbGF5_size_16_color_FFFFFF_t_70]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2NvbGRfX19wbGF5_size_16_color_FFFFFF_t_70]: /images/20210813/5006d75e6a3a4a6e924a70cdd1c9ce64.png