SpringBoot集成Swagger2在线文档

SpringBoot集成Swagger2在线文档

前言

在开发RestFul接口时,我们常常需要自己写一 接口文档,同时还要测试,很麻烦.
使用Swagger2集成,可以直接生成在线文档,同时还能直接测试,非常方便.

1.引入Swagger2的pom依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

2.添加Swagger2配置

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;

/**
 * Created by zengchao on 2018/6/6.
 */
@Configuration
@EnableSwagger2
public class Swagger2 {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包路径
                .apis(RequestHandlerSelectors.basePackage("com.xxx.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("用户库需求API文档")
                //创建人
                .contact(new Contact("JAVA组", "", ""))
                //版本号
                .version("1.0")
                //描述
                .description("此为用户库需求文档")
                .build();
    }
}

注意:该文件放在你的XXXApplication.java类的同级目录下

3.配置资源映射

默认情况下,上面两步完成,访问http://localhost:8080/swagger-ui.html就可以正常访问了.
但是,可能有的人的对静态资源做了自己的映射.根据自己情况配置.下面 是我自己的配置代码.

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

/**
 * Created by zengchao on 2018/6/14.
 */
@Configuration
public class WebConf extends WebMvcConfigurationSupport {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        //将所有/static/** 访问都映射到classpath:/static/ 目录下
        registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");
        //swagger2
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        super.addResourceHandlers(registry);
    }
}

最重要的就是下面两句

registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");

值得注意的是,我使用的是SpringBoot 2.x的版本,继承的是WebMvcConfigurationSupport,但是使用1.5X的版本,继承的是*WebMvcConfigurerAdapter,

4.接口添加注解自动生成在线API文档

在Controller类上添加注解

@Api(description = "用户相关接口")
@CrossOrigin

接口方法上添加注解

@ApiOperation(value = "1-查询用户")

实体bean上

@ApiModel

实体bean属性上

@ApiModelProperty(value = "收货手机号/昵称/用户ID")

这只是一部分注解,还有很多注解.如需了解更多,请自行搜索.

5.效果图

总体效果图
具体接口效果图