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>