SpringBoot2使用swagger2自动生成接口文档

随着技术的不断发展，现在开发的模式大部分都是前后端分离，为了跟前端同事沟通方便，大部分写后端的朋友都要写接口文档，写接口文档确实减少了跟前端同事很多不必要的沟通，但是这样就真的没有一点缺点了吗？

当接口稍微改动就得马上更新文档，然后得马上给前端发一份，这样有时候就会造成文档更新交流不及时，前端接收的文档就会多，不好管理。

就算文档更新及时了、前端也整理好了文档，也不能直接在线测试接口，通常都需要第三方插件来测试，例如postman。

但是今天我给大家介绍的swagger2就不需要，它不仅能自动生成接口文档，还能在线测试接口是否正常！

废话不多说，咱们直接进入主题，今天我们就用springboot2来整合swagger2，直接带你们应用起来。

先说一下我使用的架构和版本信息，springboot版本为2.1.6，swagger的版本为2.8，数据底层使用的是mybatis，mybatis的版本为1.3.2。

第一步：导入依赖

<!-- 导入swagger2的包-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>

第二步：配置Swagger类

/**
 * 整合swagger2
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig extends WebMvcConfigurationSupport {

    /**
     * 设置一个开关，生产版本为false，关闭swagger
     */
    @Value("${swagger.ebable}")
    private boolean ebable;

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).
                enable(ebable).select().apis(RequestHandlerSelectors.basePackage("com.demo.controller")). //扫描包
                paths(PathSelectors.any()).build();
        //可以设置为扫描多个包
        /**
         * com.google.common.base.Predicate<RequestHandler> selector1 = RequestHandlerSelectors.basePackage("设置你要扫描的包路径");
         * com.google.common.base.Predicate<RequestHandler> selector2 = RequestHandlerSelectors.basePackage("设置你要扫描的包路径");
         * createRestApi这样写即可。
         * @Bean
         *     public Docket createRestApi(){
         *         return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).
         *         enable(ebable).select().
         *         apis(Predicates.or(selector1,selector2)).
         *         paths(PathSelectors.any()).build();
         *     }
         */
    }


    @SuppressWarnings("deprecation")
    public ApiInfo apiInfo(){
        return new ApiInfoBuilder().title("接口文档").
            description("服务端通用接口").version("1.0").build();
    }

    /**
     * 一定要写这个方法，不然访问swagger-ui.html页面会404
     * @param registry
     */
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").
          addResourceLocations("classpath:/META-INF/resources/").
          setCachePeriod(0);
    }

}

SwaggerConfig类上有一个ebable属性，我们可以在yml文件上定义一下，当我们要上生产环境时，把这个ebable属性为false，swagger就关闭了。

swagger: ##给swagger设置一个开关
  ebable: true

配置好了，咱们来写一个controller。

@RestController
@Api(description = "关于用户接口",value = "用户接口",tags = {"用户接口"})  //使用@Api来修饰类
public class UserController {

    @Autowired
    private UserService userService;


    @GetMapping("/getUser/{userId}")    //使用RestFul风格
    //使用@ApiOperation注解来修饰接口
    @ApiOperation(value = "通过用户Id来获取用户信息",notes = "RestFul风格，需要传用户Id")
    //使用ApiImplcitParam修饰接口参数
    @ApiImplicitParam(name = "userId",value = "用户Id",required = true)
    public User getUserById(@PathVariable("userId") Integer userId){
        return userService.selectById(userId);
    }
}

依赖也导入了，配置也配好了，接口也写好了，咱们来启动一下这个程序吧。

启动成功后，直接访问localhost:8080/swagger-ui.html，就能看到swagger为咱们生成的接口文档了。

springboot2+swagger2的整合就到此结束了。但是swagger2还有一些注解没给大家介绍，因为swagger2是通过各种注解来生成接口文档的，下面就给大家介绍介绍swagger2的注解。

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数

整篇文章就到此结束，如果大家在整合的过程中还有什么问题可以留言给我，我也把我自己整合的源码放到github上，大家可以点击阅读原文来clone，下方也留了github的链接，也别忘记给我star哦。

github仓库链接：https://github.com/wuyanzu01/springboot2swagger2

请关注微信公众号：请快点喜欢我