Swagger2可以通过注解快速帮助我们编写最新的API接口文档。我们只需要按照它的规范去定义接口及接口相关的信息，就可以做到生成各种格式的接口文档，以及在线接口调试页面等。使用Swagger2首先要导入它的maven坐标：

  <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-boot-starter</artifactId>
     <version>3.0.0</version>
  </dependency>

导入了依赖坐标以后，我们就可以在项目中使用Swagger2帮我们生成接口文档了。我们要先熟悉一下Swagger2的常用注解:

然后，我们要创建一个实体类User和控制器UserController,并在上面添加相应的Swagger注解

注解说明
@Api用在请求的类上，例如Controller，表示对类的说明
@ApiModel用在类上，通常是实体类，表示一个返回响应数据的信息
@ApiModelProperty用在属性上，描述响应类的属性
@ApiOperation用在请求的方法上，说明方法的用途、作用
@ApiImplicitParams用在请求的方法上，表示一组参数说明
@ApiImplicitParam用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "用户实体",description = "用户实体")
public class User {
    @ApiModelProperty(value = "主键")
    private int id;
    @ApiModelProperty(value = "姓名")
    private String name;
    @ApiModelProperty(value = "年龄")
    private Integer age;
    @ApiModelProperty(value = "地址")
    private String address;
}
Swagger的基本使用
@RestController
@RequestMapping("/users")
@Api(tags = "用户控制器")
public class UserController {
    @GetMapping
    @ApiOperation(value = "查询所有用户",notes = "查询所有用户信息")
    public List<User> getAllUsers(){
        User user = new User();
        user.setId(100);
        user.setName("zhang");
        user.setAge(27);
        user.setAddress("安徽省合肥市");
        List<User> users = new ArrayList<>();
        users.add(user);
        return users;
    }
  
    @DeleteMapping("/{id}")
    @ApiImplicitParams(  //对参数的说明如：是否必需，参数类型，参数名称
            @ApiImplicitParam(name = "id",value = "用户编号",required = true,type = "Integer")
    )
    @ApiOperation(value = "删除用户", notes = "删除用户信息")
    public String delete(@PathVariable int id){
        return "OK";
    }
 }
Swagger的基本使用
Swagger的基本使用

创建好实体类和控制器以后，我们接着在SpringBoot项目中，创建Swagger的自动配置类SwaggerAutoConfiguration。这个类的作用是在里面设置一些Swagger的配置信息，并通过Spring框架进行自动加载。

/*
* Swagger2配置类
* */
@Configuration
@EnableSwagger2  //开启Swagger2,这个注解很关键
public class SwaggerAutoConfiguration {

    //配置Swagger接口文档的基本信息
    private ApiInfo apiInfo = new ApiInfoBuilder()
            .title("SwaggerAPI文档标题")  //设置接口文档的标题
            .version("1.0.1")           //设置接口文档的版本
            .contact(new Contact("zlprime","https://www.zlprime.cn","zl_al@test.com")) //设置接口文档的联系信息，需要是Contact类，在类中set联系人的姓名，url和email
            .description("这是一个API文档，遇到接口问题时请及时与后端同学联系") //设置接口文档的描述信息
            .build();


    private Docket createRestApi(){
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zlprime.controller")) //设置Swagger的包扫描路径
                .build();
        return docket;
    }
}
Swagger的基本使用

在application.yml文件中，配置一下swagger的访问端口

server:
  port: 9001

最后创建Springboot的启动类SwaggerApplication:

/*
* Swagger启动类
* */
@SpringBootApplication
public class SwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class);
    }
}

启动之后，访问地址是 localhost:端口号/swagger-ui/index.html