SpringBoot 实战 | 集成 Swagger2

什么是Swagger2

      Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

Swagger的优点  

      1、文档自动更新

      2、可以直接测试文档

      3、易于管理，一次配置即可使用

      4、接口返回结果明确，包括数据类型、状态码、错误信息。

集成步骤

       首先创建一个SpringBoot工程（开发工具idea，也可在spring官网生成工程）

 

 然后Next,finish。

 一、SpringBoot生成后，在Pom文件添加如下依赖：

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

二、在SpringBoot启动类（Application）添加Swagger注解并且在同级目录新建一个Swagger配置类（Swagger2配置类必须与Application位于同一级目录，负责生成Api文档失败），代码如下：

 

 

package com.swagger.swagger;

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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                //文档信息对象
                .apiInfo(apiInfo())
                .select()
                //被注解的包路径
                .apis(RequestHandlerSelectors.basePackage("com.swagger.swagger"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                //标题
                .title("Springboot 利用 swagger 构建 API 文档")
                //Api文档描述
                .description("SpringBoot集成Swagger")
                .termsOfServiceUrl("https://www.baidu.com")
                //文档作者信息
                .contact(new Contact("亖石磊","www.sishilei.com","sishilei@gmail.com"))
                .version("1.0")
                //文档版本
                .build();
    }
}

三、编写被注解的Controller类以及各个接口请求参数，返回结果，接口描述等，代码如下：

package com.swagger.swagger.controller;

import com.swagger.swagger.model.Car;
import com.swagger.swagger.service.CarService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping("/car")
@Api("Car Api接口文档")
public class CarController {
    @Autowired
    private CarService carService;

    @ApiOperation(value = "获取所有车辆列表",notes="获取所有车辆列表")
    @GetMapping("/list")
    public List<Car> listCar(){
        List<Car> carList = carService.listCar();
        return carList;
    }

    @PostMapping("/save")
    @ApiOperation(value = "添加车辆信息",notes="添加车辆信息")
    @ApiImplicitParam(name="car",value = "车辆实体类",required = true,dataType = "Car")
    public Car save(@RequestBody Car car){
        return carService.save(car);
    }
}

package com.swagger.swagger.model;

public class Car {
}

package com.swagger.swagger.service;

import com.swagger.swagger.model.Car;
import org.springframework.stereotype.Service;

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

@Service
public class CarService {
    public Car save(Car car) {
        return new Car();
    }

    public List<Car> listCar() {
        return new ArrayList<>();
    }
}

四、启动项目，访问http://localhost:8080/swagger-ui.html，结果图如下：

 Swagger2 常用注解简介

 

@ApiOperation：用在方法上，说明方法的作用
  1.value: 表示接口名称
  2.notes: 表示接口详细描述 
@ApiImplicitParams：用在方法上包含一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
  1.paramType：参数位置
  2.header 对应注解：@RequestHeader
  3.query 对应注解：@RequestParam
  4.path  对应注解: @PathVariable
  5.body 对应注解: @RequestBody
  6.name：参数名
  7.dataType：参数类型
  8.required：参数是否必须传
  9.value：参数的描述
  10.defaultValue：参数的默认值
@ApiResponses：用于表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
  1.code：状态码
  2.message：返回自定义信息
  3.response：抛出异常的类
@ApiIgnore: 表示该接口函数不对swagger2开放展示
@Api：修饰整个类，描述Controller的作用
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息

注意事项

@ApiImplicitParam 注解下的 paramType 属性,会影响接口的测试,如果设置的属性跟spring 的注解对应不上,会获取不到参数,例如 paramType=path ,函数内却使用@RequestParam 注解,这样,可能会获取不到传递进来的参数,需要按照上面进行对应,将 @RequestParam 注解改为 @PathVariable 才能获取到对应的参数。