SpringBoot整合Swagger2，搭建Restful API在线文档

Swagger是一个功能强大的在线API文档框架，目前它的版本是2.x，所以称为Swagger2。Swagger2提供了在线文档的查阅和测试功能。下面看看怎么在SpringBoot中集成Swagger2。

1、引入依赖

在pom文件引入下面的依赖

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

2、配置Swagger2

写一个配置类，加上相关的注解，代码如下

@Configuration
@EnableSwagger2
public class Swagger2 {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.codeliu.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot利用swagger构建api文档")
                .description("欢迎关注公众号【秃头哥编程】")
                .version("1.0")
                .build();
    }
}

其中@Configuration注解表示这是一个配置类，@EnableSwagger2开启Swagger2的功能。在配置类中需要注入一个Docket的Bean，该Bean包含了apiInfo，即基本的API文件的描述信息，以及包扫描的基本包名等信息。

3、生成文档的注解

Swagger2通过注解来生成API接口文档，文档信息包括接口名、请求方法、参数、返回信息等。通常情况下用于生成在线API文档，下面是常见的注解：

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

4、编写dao层代码

@Mapper
public interface GarbageSearchMapper {

    GarbageSearch findGarbageByName(String name);

    List<GarbageSearch> findAll();

    Integer addGarbage(GarbageSearch garbageSearch);

    Integer updateGarbage(GarbageSearch garbageSearch);

    Integer deleteGarbage(Integer id);
}

上面就是一些普通的增删改查。

5、编写Service层代码

构建一组RESTful风格的API接口。

@Service
public class GarbageSearchServiceImpl implements GarbageSearchService {

    @Autowired
    private GarbageSearchMapper garbageSearchMapper;

    public GarbageSearch findGarbageByName(String name) {
        return garbageSearchMapper.findGarbageByName(name);
    }

    public List<GarbageSearch> findAll() {
        return garbageSearchMapper.findAll();
    }

    public Integer addGarbage(GarbageSearch garbageSearch) {
        return garbageSearchMapper.addGarbage(garbageSearch);
    }

    public Integer updateGarbage(GarbageSearch garbageSearch) {
        return garbageSearchMapper.updateGarbage(garbageSearch);
    }

    public Integer deleteGarbage(Integer id) {
        return garbageSearchMapper.deleteGarbage(id);
    }
}

6、Web层

在该层通过Get、Post、Delete、Put这四种Http方法，构建一组RESTful风格的API。

@RestController
@RequestMapping("/garbage/search")
public class GarbageSearchController {

    @Autowired
    private GarbageSearchService garbageSearchService;

    @ApiOperation(value = "垃圾列表", notes = "获取所有垃圾")
    @GetMapping(value = {""})
    public List<GarbageSearch> getGarbages() {
        List<GarbageSearch> garbages = garbageSearchService.findAll();
        return garbages;
    }

    @ApiOperation(value = "增加垃圾", notes = "增加一条垃圾搜索记录")
    @PostMapping(value = "")
    public Integer postGarbage(@RequestBody GarbageSearch garbageSearch) {
        return garbageSearchService.addGarbage(garbageSearch);
    }

    @ApiOperation(value = "删除垃圾搜索记录", notes = "根据垃圾的id删除垃圾搜索记录")
    @DeleteMapping(value = "/{id}")
    public Integer deleteGarbage(@PathVariable Integer id) {
        return garbageSearchService.deleteGarbage(id);
    }

    @ApiOperation(value = "更新信息", notes = "根据指定的id更新垃圾搜索记录")
    @PutMapping(value = "/{id}")
    public Integer putGarbage(@PathVariable Integer id, @RequestBody GarbageSearch garbageSearch) {
        GarbageSearch garbageSearch1 = new GarbageSearch();
        garbageSearch1.setGarbageSearchCount(garbageSearch.getGarbageSearchCount() + 1);
        garbageSearch1.setGarbageSearchId(id);

        return garbageSearchService.updateGarbage(garbageSearch);
    }

    @ApiIgnore
    @GetMapping(value = "/hi")
    public String test() {
        return "hello world";
    }
}

通过@ApiOperation注解描述生成在线文档的具体API的说明，其中value值为该接口的名称，note为该接口的详细文档说明。这样就可以让Swagger2生成在线的API接口文档了，如果不需要某接口生成文档，只需要加上@ApiIgnore注解即可。

启动项目，输入http://localhost:{项目端口号}/swagger-ui.html，浏览器就会生成接口文档。
在这里插入图片描述
点开接口，还可以看到详细信息包括参数和返回值、错误码等信息。