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

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查看