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

迷南。 2022-12-27 07:43 272阅读 0赞

平凡也就两个字: 懒和惰;  
成功也就两个字: 苦和勤;  
优秀也就两个字: 你和我。  
跟着我从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依赖包 ###

<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

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0lUX01vc3Q_size_16_color_FFFFFF_t_70][]

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

### 2.6 在线测试api接口 ###

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

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

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0lUX01vc3Q_size_16_color_FFFFFF_t_70 1][]

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

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0lUX01vc3Q_size_16_color_FFFFFF_t_70 2][]

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

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0lUX01vc3Q_size_16_color_FFFFFF_t_70 3][]

## 3 swagger常用注解讲解 ##

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

<table style="width:600px;"> 
 <thead> 
  <tr> 
   <th>注解</th> 
   <th>作用</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><span style="color:#f33b45;">@Api</span></td> 
   <td>用在Controller类上，对所标注的类进行描述说明。</td> 
  </tr> 
  <tr> 
   <td><span style="color:#f33b45;">@ApiOperation</span></td> 
   <td>用在COntroller类中的方法上，对所标注的方法进行描述说明。</td> 
  </tr> 
  <tr> 
   <td><span style="color:#f33b45;">@ApiParam</span></td> 
   <td>用于 Controller 中方法的参数说明。</td> 
  </tr> 
  <tr> 
   <td>@ApiImplicitParams</td> 
   <td>组装多个@ApiImplicitParam</td> 
  </tr> 
  <tr> 
   <td>@ApiImplicitParam</td> 
   <td>用在方法上，对方法的参数进行单独说明。</td> 
  </tr> 
  <tr> 
   <td><span style="color:#f33b45;">@ApiModel</span></td> 
   <td>用在实体类上，对实体类进行说明。</td> 
  </tr> 
  <tr> 
   <td><span style="color:#f33b45;">@ApiModelProperty</span></td> 
   <td>用于字段，表示对 model 属性的说明。使用方式代码如下所示。</td> 
  </tr> 
  <tr> 
   <td>@ApiResponse</td> 
   <td>用于方法上，说明接口响应的一些信息</td> 
  </tr> 
  <tr> 
   <td>@ApiResponses</td> 
   <td>组装了多个 @ApiResponse</td> 
  </tr> 
 </tbody> 
</table>

### 3.1 @Api注解 ###

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

<table style="width:500px;"> 
 <tbody> 
  <tr> 
   <td>注解属性</td> 
   <td>字段类型</td> 
   <td>描述</td> 
  </tr> 
  <tr> 
   <td>value</td> 
   <td>String</td> 
   <td>url的路径</td> 
  </tr> 
  <tr> 
   <td><span style="color:#f33b45;">tags</span></td> 
   <td>String[]</td> 
   <td>接口类标签列表</td> 
  </tr> 
  <tr> 
   <td>description</td> 
   <td>String</td> 
   <td>接口类描述</td> 
  </tr> 
  <tr> 
   <td>hidden</td> 
   <td>boolean</td> 
   <td>是否隐藏该接口类api文档</td> 
  </tr> 
 </tbody> 
</table>

### 3.2 @ApiOperation注解 ###

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

<table style="width:500px;"> 
 <tbody> 
  <tr> 
   <td>注解属性</td> 
   <td>字段类型</td> 
   <td>描述</td> 
  </tr> 
  <tr> 
   <td><span style="color:#f33b45;">value</span></td> 
   <td>String</td> 
   <td>接口说明</td> 
  </tr> 
  <tr> 
   <td><span style="color:#f33b45;">notes</span></td> 
   <td>String</td> 
   <td>接口补充描述</td> 
  </tr> 
  <tr> 
   <td>tags</td> 
   <td>String[]</td> 
   <td>接口标签</td> 
  </tr> 
  <tr> 
   <td>httpMethod</td> 
   <td>String</td> 
   <td>接口请求方式</td> 
  </tr> 
 </tbody> 
</table>

### 3.3 @ApiIgnore注解 ###

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

<table style="width:500px;"> 
 <tbody> 
  <tr> 
   <td>注解属性</td> 
   <td>字段类型</td> 
   <td>描述</td> 
  </tr> 
  <tr> 
   <td>value</td> 
   <td>String</td> 
   <td>屏蔽接口的描述</td> 
  </tr> 
 </tbody> 
</table>

### 3.4 @ApiModel注解 ###

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

<table style="width:500px;"> 
 <tbody> 
  <tr> 
   <td>注解属性</td> 
   <td>字段类型</td> 
   <td>描述</td> 
  </tr> 
  <tr> 
   <td>value</td> 
   <td>String</td> 
   <td>接口实体类别名</td> 
  </tr> 
  <tr> 
   <td><span style="color:#f33b45;">description</span></td> 
   <td>String</td> 
   <td>接口实体类描述</td> 
  </tr> 
 </tbody> 
</table>

### 3.5 @ApiModelProperty注解 ###

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

<table style="width:500px;"> 
 <tbody> 
  <tr> 
   <td>注解属性</td> 
   <td>字段类型</td> 
   <td>描述</td> 
  </tr> 
  <tr> 
   <td><span style="color:#f33b45;">value</span></td> 
   <td>String</td> 
   <td>接口实体类属性描述</td> 
  </tr> 
  <tr> 
   <td>name</td> 
   <td>String</td> 
   <td>重写接口实体类属性名称</td> 
  </tr> 
  <tr> 
   <td><span style="color:#f33b45;">example</span></td> 
   <td>String</td> 
   <td>属性示例</td> 
  </tr> 
  <tr> 
   <td><span style="color:#f33b45;">required</span></td> 
   <td>boolean</td> 
   <td>属性是否为必填字段</td> 
  </tr> 
 </tbody> 
</table>

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

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

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0lUX01vc3Q_size_16_color_FFFFFF_t_70 4][]

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

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0lUX01vc3Q_size_16_color_FFFFFF_t_70 5][]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0lUX01vc3Q_size_16_color_FFFFFF_t_70]: /images/20221120/b6faa11220254f82b48e11439c399f9e.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0lUX01vc3Q_size_16_color_FFFFFF_t_70 1]: /images/20221120/3aeb50e5c3de4d7397bc568374d19bf7.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0lUX01vc3Q_size_16_color_FFFFFF_t_70 2]: /images/20221120/b936f08c688c4bba92911ad41bdeb423.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0lUX01vc3Q_size_16_color_FFFFFF_t_70 3]: /images/20221120/0795a00b7c394d16b9d1673fd41a6208.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0lUX01vc3Q_size_16_color_FFFFFF_t_70 4]: /images/20221120/63c2f38b6d974cedb1141dcc83a50bf5.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0lUX01vc3Q_size_16_color_FFFFFF_t_70 5]: /images/20221120/1703ec3a72844e9a8c13825596b14b12.png