Spring boot整合Swagger2 -- 自动构建接口文档

古城微笑少年丶 2023-07-03 12:11 34阅读 0赞

#### 简述 ####

如果你是一名后端项目开发者，你写好了接口，前端人员如果想知道，就需要你们之前协调书写一个API接口文档来进行交流。

API接口文档难写不说，维护也是一个问题。

我们何不让他自己生成动态接口文档呢？ Swagger就扮演这样一个角色，起到了这样一个作用。  
![在这里插入图片描述][20200206155149637.png]  
Swagger提供了用于生成，可视化和维护API文档的一系列解决方案，使API文档的编辑不再需要人工操作。

#### Spring boot项目中整合Swagger2 ####

**1.目前最新版本是`2.9.2`，所以我们在项目的`pom.xml`文件中导入相关依赖**

<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>

右下角，导入`pom.xml`文件的改变  
![在这里插入图片描述][20200206145228934.png]  
**2.创建Swagger2配置类**

/**
     * @author 阳光大男孩！！！
     */
    @Configuration
    @EnableSwagger2
    public class Swagger2Config {
        
    
        @Bean
        public Docket webApiConfig() {
        
            return new Docket(DocumentationType.SWAGGER_2)
                    .groupName("webApi")
                    //用于指定文档信息
                    .apiInfo(apiInfo())
                    .select()
                    .build();
        }
    
        private ApiInfo apiInfo() {
        
            return new ApiInfoBuilder()
                    .title("接口文档")
                    .description("本文档是描述xxxxx")
                    .version("1.0")
                    .contact(new Contact("阳光大男孩", "https://blog.csdn.net/weixin_43889841", "xxx"))
                    .build();
        }
    
    }

**3.如果你的端口开放的是8080，那么访问`http://localhost:8080/swagger-ui.html`，一个接口文档就生成了**

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mzg4OTg0MQ_size_16_color_FFFFFF_t_70]

**4.除此之外，亦可以像postman测试接口一样，测试API**  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mzg4OTg0MQ_size_16_color_FFFFFF_t_70 1]  
我们测试的是一个用于购买商品的接口，由于我们的库存已经是0，所以返回了状态码为`200`，信息为抢购失败的信息。  
![在这里插入图片描述][20200206154934135.png]

#### 相关注解 ####

<table> 
 <thead> 
  <tr> 
   <th>注解</th> 
   <th>作用</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>@Api</td> 
   <td>修饰整个类，用于controller类上</td> 
  </tr> 
  <tr> 
   <td>@ApiOperation</td> 
   <td>描述一个接口，用户controller方法上</td> 
  </tr> 
  <tr> 
   <td>@ApiParam</td> 
   <td>单个参数描述</td> 
  </tr> 
  <tr> 
   <td>@ApiModel</td> 
   <td>用来对象接收参数,即返回对象</td> 
  </tr> 
  <tr> 
   <td>@ApiModelProperty</td> 
   <td>对象接收参数时，描述对象的字段</td> 
  </tr> 
  <tr> 
   <td>@ApiResponse</td> 
   <td>Http响应其中的描述，在ApiResonse中</td> 
  </tr> 
  <tr> 
   <td>@ApiResponses</td> 
   <td>Http响应所有的描述，用在</td> 
  </tr> 
  <tr> 
   <td>@ApiIgnore</td> 
   <td>忽略这个API</td> 
  </tr> 
  <tr> 
   <td>@ApiError</td> 
   <td>发生错误的返回信息</td> 
  </tr> 
  <tr> 
   <td>@ApiImplicitParam</td> 
   <td>一个请求参数</td> 
  </tr> 
  <tr> 
   <td>@ApiImplicitParam</td> 
   <td>多个请求参数</td> 
  </tr> 
 </tbody> 
</table>

**这些注解是用来干什么的？**

用来控制接口文档的显示内容。

例如刚才我们购买商品的接口  
![在这里插入图片描述][2020020616054676.png]  
并没有注释这个接口是干嘛的，我们则可以使用`@ApiOperation` 注解。

@ApiOperation("购买商品的接口")
        @PostMapping("/purchase")
        public RespBean purchase(Long userId,Long productId,Integer num)
        {
        
            System.out.println("1");
            boolean success=purchaseProductService.purchase(productId,userId,num);
            if(success)
            {
        
                return RespBean.ok("抢购成功");
            }
            return RespBean.ok("抢购失败");
        }

重启项目，此时该接口已经有了相关说明  
![在这里插入图片描述][20200206160740738.png]

其他注解的测试，大家有兴趣可以自己测试一下。

[20200206155149637.png]: https://img-blog.csdnimg.cn/20200206155149637.png
[20200206145228934.png]: https://img-blog.csdnimg.cn/20200206145228934.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mzg4OTg0MQ_size_16_color_FFFFFF_t_70]: https://img-blog.csdnimg.cn/20200206150239481.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mzg4OTg0MQ==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mzg4OTg0MQ_size_16_color_FFFFFF_t_70 1]: https://img-blog.csdnimg.cn/20200206154834568.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mzg4OTg0MQ==,size_16,color_FFFFFF,t_70
[20200206154934135.png]: https://img-blog.csdnimg.cn/20200206154934135.png
[2020020616054676.png]: https://img-blog.csdnimg.cn/2020020616054676.png
[20200206160740738.png]: https://img-blog.csdnimg.cn/20200206160740738.png