Swgger2的简单使用

编写接口文档是一个非常枯燥的工作，我们采用Swagger2这套自动化文档工具来生成文档，它可以轻松的整合到Spring Boot中，并与Spring MVC程序配合组织出强大RESTful API文档。

1、在pom.xml文件中加入Swagger2的依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2、创建Swagger2配置类

 package com.offcn.springbootdemo2.Config;

 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import springfox.documentation.builders.ApiInfoBuilder;
 import springfox.documentation.builders.PathSelectors;
 import springfox.documentation.builders.RequestHandlerSelectors;
 import springfox.documentation.service.ApiInfo;
 import springfox.documentation.spi.DocumentationType;
 import springfox.documentation.spring.web.plugins.Docket;
 import springfox.documentation.swagger2.annotations.EnableSwagger2;

 @Configuration
 @EnableSwagger2
 public class SwaggerConfig {

    @Bean
    public Docket createRestApi(){
       return new Docket(DocumentationType.SWAGGER_2)
             .apiInfo(apiInfo())
             .select().apis(RequestHandlerSelectors.basePackage("com.offcn.springbootdemo2.Controller"))
             .paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo() {
       return new ApiInfoBuilder().title("RestFul风格").description("一种好的习惯")
             .termsOfServiceUrl("http://www.baidu.com").contact("java").version("1.0").build();
    }
 }

3、修改Controller增加文档注释

 package com.offcn.springbootdemo2.Controller;

 import com.offcn.springbootdemo2.Pojo.User;
 import io.swagger.annotations.ApiImplicitParam;
 import io.swagger.annotations.ApiImplicitParams;
 import io.swagger.annotations.ApiOperation;
 import org.springframework.web.bind.annotation.*;

 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;

 @RestController
 @RequestMapping("/user")
 public class UserController {

    private List<User> listUser= Collections.synchronizedList(new ArrayList<User>());
    @GetMapping("/")
    public List<User> getUserList(){
       return listUser;
    }

    /***
     * 新增用户
     * @param user
     * @return
     */
    @PostMapping("/")
    public String createUser(User user) {
       listUser.add(user);
       return "success";
    }

    /***
     * 获取指定id用户信息
     * @param id
     * @return
     */
    @GetMapping("/{id}")

    public User getUser(@PathVariable("id") Integer id) {
       for (User user : listUser) {
          if(user.getId()==id) {
             return user;
          }
       }
       return null;
    }
    /**
     * 更新指定id用户信息
     * @param id
     * @param user
     * @return
     */
    @PutMapping("/{id}")
    @ApiOperation(value="更新指定id用户信息", notes="根据id更新用户信息")
    @ApiImplicitParams({
          @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),
          @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
    })
    public String updateUser(@PathVariable("id") Integer id,User user) {
       for (User user2 : listUser) {
          if(user2.getId() == id) {
             user2.setName(user.getName());
             user2.setAge(user.getAge());
          }
       }
       return "success";
    }

    /***
     * 删除指定id用户
     * @param id
     * @return
     */
    @DeleteMapping("/{id}")
    @ApiOperation(value="删除指定id用户信息", notes="根据id删除用户信息")
    @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "Long")
    public String deleteUser(@PathVariable("id") Integer id) {

       listUser.remove(getUser(id));
       return "success";

    }
 }

4、启动项目，在浏览器地址输入

http://localhost:8080/swagger-ui.html

查看Swagger2文档

额外添加一个依赖Lombok，可以省略实体类中繁琐的代码

<!-- https://mvnrepository.com/artifact/org.projectlombok/lombok -->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.10</version>
    <scope>provided</scope>
</dependency>