springboot整合swagger2实现自动生成api文档

平凡也就两个字: 懒和惰;
成功也就两个字: 苦和勤;
优秀也就两个字: 你和我。
跟着我从0学习JAVA、spring全家桶和linux运维等知识，带你从懵懂少年走向人生巅峰，迎娶白富美！
关注微信公众号【 IT特靠谱 】，每天都会分享技术心得~

springboot整合swagger2实现自动生成api文档

1 swagger2简介

      翻译自swagger2官网的简介：无论您是开发团队还是最终用户，你都无需任何实现逻辑就可以通过Swagger UI查看和使用API资源。swagger文档是根据您的OpenAPI并安装Swagger规范自动生成的。也就是说：（1）swagger文档是通过代码直接生成的，不再需要自己手动编写接口文档了；（2）Swagger 文档支持在线测试。参数和格式都定好了，直接在ui界面上输入参数值即可在线测试接口。

      Tips：如果需要本教程示例demo代码，关注微信公众号：IT特靠谱，完整回复"我要swagger代码"即可免费获取下载地址~

2 springboot项目整合swagger2

2.1 引入swagger2依赖包

    <!--swagger2依赖包-->
    <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>

2.2 创建配置文件

      创建swagger2配置文件：Swagger2Config.java

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;

/**
 * swagger2配置类
 */
@Configuration
@EnableSwagger2 //启用swagger2
public class Swagger2Config {

  @Bean
  public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.xxx.alltest.controller"))//设置当前Dokcet所需要扫描的包，这种方式我们可以通过指定包名的方式，让Swagger只去某些包下面扫描接口
        .paths(PathSelectors.any())
        .build();
  }

  /**
   * Api文档的基本信息
   */
  private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
        .title("xx项目Restful Apis")
        .version("1.0")
        .description("xx项目Api文档")
        .termsOfServiceUrl("http://www.baidu.com")
        .contact(new Contact("微信公众号：IT特靠谱", "https://blog.csdn.net/IT_Most", "123456@qq.com"))
        .build();
  }
}

2.3 创建Vo类

      创建AccountVo类：AccountVo.java

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import java.io.Serializable;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(description = "账户Vo")
public class AccountVo implements Serializable {

  @ApiModelProperty(value = "账户名称", example = "IT特靠谱")
  private String accountName;

  @ApiModelProperty(value = "联系地址", example = "https://blog.csdn.net/IT_Most")
  private String contactUrl;
}

2.4 创建控制器

      创建账号控制器：AccountController.java，并提供3个接口（find、insert和delete），3个接口都是极简的接口，省去了业务逻辑，仅仅用于测试。

import com.xxx.alltest.entity.AccountVo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;

@RestController
@RequestMapping(value = "/account")
@Api(tags = "账户信息controller", description = "账户信息controller")
public class AccountController {

  @GetMapping("find")
  @ApiOperation(value = "查询", notes = "根据账户名称查询账户信息")
  public AccountVo find(@RequestParam("accountName") String accountName){
    return AccountVo.builder()
        .accountName(accountName)
        .contactUrl("https://blog.csdn.net/IT_Most")
        .build();
  }

  @PostMapping("insert")
  @ApiOperation(value = "新增", notes = "新增一个账户信息")
  public String insert(@RequestBody AccountVo accountVo){
    return "新增成功!" + accountVo.toString();
  }

  @PostMapping("delete")
  @ApiIgnore //swagger2 ui不显示该api
  @ApiOperation(value = "删除", notes = "删除指定账户名的信息")
  public String delete(String accountName){
    return "删除成功!" + accountName;
  }
}

2.5 启动项目，查看api文档

      启动项目后，浏览器访问：http://localhost:8080/swagger-ui.html

      可以看到swagger自动给我们项目中的find和insert api生成了文档。但是没有未delete接口生成文档，是因为再delete接口方法上有@ApiIgnore注解。

2.6 在线测试api接口

      我们以"/account/find"接口为例，演示swagger ui在线访问接口的操作。

      展开find接口文档详情，点击"Try it out"按钮。

      填写接口请求参数accountName，值为：IT特靠谱。

      点击"Excute"按钮发起请求到后台服务器。

3 swagger常用注解讲解

      下面表格中列出了swagger的注解。红色标记的注解为常用注解或注解属性。

注解	作用
@Api	用在Controller类上，对所标注的类进行描述说明。
@ApiOperation	用在COntroller类中的方法上，对所标注的方法进行描述说明。
@ApiParam	用于 Controller 中方法的参数说明。
@ApiImplicitParams	组装多个@ApiImplicitParam
@ApiImplicitParam	用在方法上，对方法的参数进行单独说明。
@ApiModel	用在实体类上，对实体类进行说明。
@ApiModelProperty	用于字段，表示对 model 属性的说明。使用方式代码如下所示。
@ApiResponse	用于方法上，说明接口响应的一些信息
@ApiResponses	组装了多个 @ApiResponse

3.1 @Api注解

      在控制器Controller类上增加 @Api 注解，可以给控制器增加描述和标签信息。常用的属性有：value和description。

注解属性	字段类型	描述
value	String	url的路径
tags	String[]	接口类标签列表
description	String	接口类描述
hidden	boolean	是否隐藏该接口类api文档

3.2 @ApiOperation注解

      在接口方法上增加 @ApiOperation 注解，可以给接口增加描述信息。常用的属性有：value和notes。

注解属性	字段类型	描述
value	String	接口说明
notes	String	接口补充描述
tags	String[]	接口标签
httpMethod	String	接口请求方式

3.3 @ApiIgnore注解

      如果需要再swagger api文档中屏蔽掉（隐藏）删除账户信息接口（/account/delete），那么只需要在删除账户接口方法上加上 @ApiIgnore 注解即可。该注解只有value属性，即屏蔽接口的描述。

注解属性	字段类型	描述
value	String	屏蔽接口的描述

3.4 @ApiModel注解

      在接口实体类上增加@ApiModel注解，以给接口实体类增加描述信息。

注解属性	字段类型	描述
value	String	接口实体类别名
description	String	接口实体类描述

3.5 @ApiModelProperty注解

      在接口实体类属性上增加@ApiModelProperty注解，以给接口实体类的属性增加描述信息。

注解属性	字段类型	描述
value	String	接口实体类属性描述
name	String	重写接口实体类属性名称
example	String	属性示例
required	boolean	属性是否为必填字段

      

    （1） 商务合作微信号：M9392W

    （2） 购物商城： 扫码即可进入博主开发的小程序购物商城，享超大优惠购物，支持一下博主吧~

    （3） 博主微信公众号：IT特靠谱，学习更多开发实战技巧！