SpringBoot 2.X集成Swagger2生成 RESTFul 风格API接口文档

约定不等于承诺〃 2022-02-25 02:46 330阅读 0赞

### 文章目录 ###

*   *   *  1 摘要
         *  2 Maven 依赖
         *  3 配置与使用 Swagger2
         *   *  3.1 配置 Swagger 2
             *  3.2 使用 Swagger 注解
         *  4 测试
         *  5 注意事项
         *  6 参考资料推荐
         *  7 Github 源码

### 1 摘要 ###

在开发过程中，很多后台开发者没有写接口文档的习惯，而接手没有文档的项目令人狂抓，因此在二次开发时大量的时间浪费在解读原代码的过程中。Swagger 是一款优秀的接口文档生成框架，使用注解就可以自动生成接口文档，省去了后台开发者专门写接口文档的时间，也让项目的可读性变得更好。本文将介绍 Spring Boot 2.X 集成 Swagger 2 的教程。

Swagger 官方文档: [https://swagger.io/][https_swagger.io]

### 2 Maven 依赖 ###

../pom.xml
    ../demo-common/pom.xml
    ../demo-model/pom.xml

<dependency>
                    <groupId>io.springfox</groupId>
                    <artifactId>springfox-swagger2</artifactId>
                    <version>${swagger2.version}</version>
                </dependency>
                <dependency>
                    <groupId>io.springfox</groupId>
                    <artifactId>springfox-swagger-ui</artifactId>
                    <version>${swagger2.version}</version>
                </dependency>

其中对应的版本号为:

<swagger2.version>2.9.2</swagger2.version>

### 3 配置与使用 Swagger2 ###

#### 3.1 配置 Swagger 2 ####

../demo-common/src/main/java/com/ljq/demo/springboot/common/config/Swagger2Config.java

package com.ljq.demo.springboot.common.config;
    
    import org.springframework.beans.factory.annotation.Value;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    /** * @Description: Swagger2 配置信息 * @Author: junqiang.lu * @Date: 2019/3/23 */
    @Configuration
    @EnableSwagger2
    public class Swagger2Config { 
    
        @Value("${swagger.enable}")
        private boolean enableSwagger;
    
        @Bean
        public Docket api() { 
            return new Docket(DocumentationType.SWAGGER_2)
                    .enable(enableSwagger)
                    .select()
                    .apis(RequestHandlerSelectors.any())
                    .paths(PathSelectors.any())
                    .build();
        }
    }

其中使用 `${swagger.enable}` 属性是为了实现根据不同环境动态开启 `Swagger` 。如在开发环境开启 `Swagger` ,而在生产环境关闭 `Swagger` 功能。

在 `yml` 配置`swagger` 属性

../demo-web/src/main/resources/application-dev.yml
    ../demo-web/src/main/resources/application-test.yml

# Swagger config
    swagger:
      enable: true

../demo-web/src/main/resources/application-pro.yml

# Swagger config
    swagger:
      enable: false

#### 3.2 使用 Swagger 注解 ####

参数接收类

../demo-model/src/main/java/com/ljq/demo/springboot/vo/swagger2/ModelAnnotationBean.java

package com.ljq.demo.springboot.vo.swagger2;
    
    import com.ljq.demo.springboot.BaseBean;
    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    import lombok.Data;
    
    import javax.validation.constraints.Min;
    import javax.validation.constraints.NotNull;
    import javax.validation.constraints.Pattern;
    
    /** * @Description: Swagger2 注解示例 bean * @Author: junqiang.lu * @Date: 2019/3/23 */
    @Data
    @ApiModel(value = "Swagger2 @ApiModel 注解",description = "Swagger 2 注解接收参数")
    public class ModelAnnotationBean extends BaseBean { 
    
        private static final long serialVersionUID = -3891566801822635611L;
    
        // 当前页
        @NotNull(message = "当前页不能为空")
        @Min(value = 1, message = "当前页至少为 1")
        @ApiModelProperty(value = "当前页,不能为空,至少为 1", name = "currPage", required = true, example = "1")
        private Integer currPage;
    
        // 每页显示条数
        @NotNull(message = "每页显示条数不能为空")
        @Min(value = 5, message = "每页至少展示 5 条结果")
        @ApiModelProperty(value = "每页显示条数,不能为空,至少为 5", name = "pageLimit", required = true, example = "6")
        private Integer pageLimit;
    
         // 排序依据,如依据 "id" 排序
        @NotNull(message = "排序依据不能为空")
        @Pattern(regexp = "^[\\s\\S]{1,30}$", message = "排序依据需要控制在 1-30 个字符以内")
        @ApiModelProperty(value = "排序依据,不能为空,1-30 个字符", name = "sidx", required = true, example = "id")
        private String sidx;
    
        // 排序规则,升序: asc;降序: desc
        @NotNull(message = "排序规则不能为空")
        @Pattern(regexp = "^[\\s\\S]{1,10}$", message = "排序规则需要控制在 1-10 个字符以内")
        @ApiModelProperty(value = "排序规则,升序:asc;降序:desc", name = "order",required = true, example = "desc")
        private String order;
    }

Controller 层注解

../demo-web/src/main/java/com/ljq/demo/springboot/web/controller/Swagger2Controller.java

package com.ljq.demo.springboot.web.controller;
    
    import com.ljq.demo.springboot.common.api.ApiResult;
    import com.ljq.demo.springboot.common.api.ResponseCode;
    import com.ljq.demo.springboot.common.exception.ParamsCheckException;
    import com.ljq.demo.springboot.service.Swagger2Service;
    import com.ljq.demo.springboot.vo.swagger2.ModelAnnotationBean;
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiOperation;
    import lombok.extern.slf4j.Slf4j;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.web.bind.annotation.RequestBody;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RequestMethod;
    import org.springframework.web.bind.annotation.RestController;
    
    /** * @Description: Swagger2 示例控制中心 * @Author: junqiang.lu * @Date: 2019/3/23 */
    @RestController
    @RequestMapping(value = "api/swagger2")
    @Slf4j
    @Api(value = "Swagger 2 控制层", tags = "Swagger 2 控制层")
    public class Swagger2Controller { 
    
        @Autowired
        private Swagger2Service swagger2Service;
    
        /** * 实体类注解测试 * * @param modelAnnotationBean * @return */
        @RequestMapping(value = "modelAnnotation", method = RequestMethod.POST)
        @ApiOperation(value = "Swagger 2 注解示范",notes = "Swagger 2 注解示范")
        public ApiResult modelAnnotation(@RequestBody ModelAnnotationBean modelAnnotationBean) { 
    
            ApiResult apiResult = null;
            try { 
                apiResult = swagger2Service.modelAnnotation(modelAnnotationBean);
            } catch (Exception e) { 
                if (ParamsCheckException.class.isAssignableFrom(e.getClass())){ 
                    log.error("参数错误");
                    return apiResult.failure(ResponseCode.PARAM_ERROR.getCode(), e.getMessage());
                }
                log.error("未知异常",e);
                return apiResult.failure(ResponseCode.UNKNOWN_ERROR.getMsg());
            }
    
            return apiResult;
        }
    
    }

其他模块示例代码(不涉及 Swagger 使用)

Service 层

../demo-service/src/main/java/com/ljq/demo/springboot/service/Swagger2Service.java

package com.ljq.demo.springboot.service;
    
    import com.ljq.demo.springboot.common.api.ApiResult;
    import com.ljq.demo.springboot.vo.swagger2.ModelAnnotationBean;
    
    /** * @Description: Swagger2 业务接口 * @Author: junqiang.lu * @Date: 2019/3/23 */
    public interface Swagger2Service { 
    
        /** * Swagger2 参数接受实体类注解@ApiModel...示例 * * @param modelAnnotationBean * @return * @throws Exception */
        ApiResult modelAnnotation(ModelAnnotationBean modelAnnotationBean) throws Exception;
    
    }

../demo-service/src/main/java/com/ljq/demo/springboot/service/impl/Swagger2ServiceImpl.java

package com.ljq.demo.springboot.service.impl;
    
    import com.ljq.demo.springboot.common.api.ApiResult;
    import com.ljq.demo.springboot.common.page.PageUtil;
    import com.ljq.demo.springboot.common.page.QueryUtil;
    import com.ljq.demo.springboot.common.util.MapUtil;
    import com.ljq.demo.springboot.dao.user.UserDao;
    import com.ljq.demo.springboot.entity.UserDO;
    import com.ljq.demo.springboot.service.Swagger2Service;
    import com.ljq.demo.springboot.vo.swagger2.ModelAnnotationBean;
    import lombok.extern.slf4j.Slf4j;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.stereotype.Service;
    import org.springframework.transaction.annotation.Transactional;
    
    import java.util.List;
    import java.util.Map;
    
    /** * @Description: Swagger2 业务具体实现类 * @Author: junqiang.lu * @Date: 2019/3/23 */
    @Service("swagger2Service")
    @Transactional(rollbackFor = Exception.class)
    @Slf4j
    public class Swagger2ServiceImpl implements Swagger2Service { 
    
        @Autowired
        private UserDao userDao;
    
        /** * Swagger2 参数接受实体类注解@ApiModel...示例 * * @param modelAnnotationBean * @return * @throws Exception */
        @Override
        public ApiResult modelAnnotation(ModelAnnotationBean modelAnnotationBean) throws Exception { 
            /** * 获取参数 */
            Map<String, Object> map = MapUtil.beanToMap(modelAnnotationBean);
            QueryUtil queryUtil = new QueryUtil(map);
            // 列表查询
            List<UserDO> userDBList = userDao.queryList(queryUtil);
            if (userDBList == null || userDBList.isEmpty()) { 
                return ApiResult.success(new PageUtil(null, 0, queryUtil.getPageLimit(), queryUtil.getCurrPage()));
            }
    
            int total = userDao.queryCount(queryUtil);
            // 分页处理
            PageUtil pageUtil = new PageUtil(userDBList, total, queryUtil.getPageLimit(), queryUtil.getCurrPage());
    
            return ApiResult.success(pageUtil);
        }
    }

### 4 测试 ###

启动项目,打开以下链接

http://localhost:8088/swagger-ui.html

界面显示如下:  
![springBoot2-Swagger2-1][]  
`Swagger` 界面使用步骤:

*  1 点击其中的一个接口展开接口详情
 *  2 点击 「Model」 查看接口请求参数信息(要求)
 *  3 点击 「Try it out」 进入接口测试模式
 *  4 点击「Execute」请求接口,此时可以修改请求参数
 *  5 查看接口请求结果

![springBoot2-Swagger2-2][]  
![springBoot2-Swagger2-3][]  
![springBoot2-Swagger2-4][]

### 5 注意事项 ###

*  在使用 `Swagger` 注解的时候, 同一个注解 `value` 值不能设置相同，否则会出现在界面上显示不同的接口，但是接口参数却相同

如下图,有两个接口,一个 `Save` 接口,一个 `FindById` 接口，两个接口的请求参数不同，使用 `@ApiModel` 注解时设置的`value` 值相同，结果导致在 `swagger-ui` 界面两个接口显示的参数相同，从而导致在请求接口时请求的参数并不是实际接口所需要的参数

![springBoot2-Swagger2-5][]  
![springBoot2-Swagger2-6][]  
 ![springBoot2-Swagger2-7][]  
![springBoot2-Swagger2-8][]

### 6 参考资料推荐 ###

[Setting Up Swagger 2 with a Spring REST API][]

[Spring Boot RESTful API Documentation with Swagger 2][]

[配置不同环境下启用swagger，在生产环境关闭swagger][swagger_swagger]

### 7 Github 源码 ###

**Gtihub 源码地址** : [https://github.com/Flying9001/springBootDemo][https_github.com_Flying9001_springBootDemo]  
个人公众号:**404Code**,分享半个互联网人的技术与思考，感兴趣的可以关注.  
![404Code][]

[https_swagger.io]: https://swagger.io/
[springBoot2-Swagger2-1]: /images/20220225/57a23baeab8149678aceb88a9d0d72ec.png
[springBoot2-Swagger2-2]: /images/20220225/736d7895b03e4162a3666abd664f7893.png
[springBoot2-Swagger2-3]: /images/20220225/f8683639beed4cc9a4c5067407b03a1f.png
[springBoot2-Swagger2-4]: /images/20220225/ed121c070cd742fdb5755ed7c6c91b41.png
[springBoot2-Swagger2-5]: /images/20220225/fdd7b895befc48bcbb8ffec99cb478ef.png
[springBoot2-Swagger2-6]: /images/20220225/5f98e29b35ac40d9bed12dd823d0ed91.png
[springBoot2-Swagger2-7]: /images/20220225/aa2242b5a5e74b75af0b78313c561efb.png
[springBoot2-Swagger2-8]: /images/20220225/f3b0f871e4e44f989ff210163f29a6dd.png
[Setting Up Swagger 2 with a Spring REST API]: https://www.baeldung.com/swagger-2-documentation-for-spring-rest-api
[Spring Boot RESTful API Documentation with Swagger 2]: https://springframework.guru/spring-boot-restful-api-documentation-with-swagger-2/
[swagger_swagger]: https://www.cnblogs.com/woshimrf/p/disable-swagger.html
[https_github.com_Flying9001_springBootDemo]: https://github.com/Flying9001/springBootDemo
[404Code]: /images/20220225/fc1cd2c60a7e4f0aae6da41bea27657e.png