Springboot Swagger2 快速详细配置（简单易学代码注释多）

一、简介

一份解决前后端分离开发的接口文档，详细解释自行百度。

二、使用前提

• jdk 1.8 +
• Springboot

三、配置

1. 创建一个Springboot-web工程
2. 添加Maven依赖

<!-- swagger2 文档-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- swagger-ui 文档ui界面-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

3. 编写配置类

@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class Swagger2Config extends WebMvcConfigurationSupport{

    @Bean //配置docket以配置Swagger具体参数
    public Docket docket(Environment environment) {

        // 设置要显示swagger的环境，生产环境下不显示
        Profiles of = Profiles.of("dev", "test");
        // 判断当前是否处于该环境
        // 通过 enable() 接收此参数判断是否要显示
        boolean flag = environment.acceptsProfiles(of);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 配置是否启用Swagger，如果是false，在浏览器将无法访问
                .enable(flag)
                // 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                .select()
                /* RequestHandlerSelectors配置方法
                 * any() // 扫描所有，项目中的所有接口都会被扫描到
                 * none() // 不扫描接口
                 * // 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
                 * withMethodAnnotation(final Class<? extends Annotation> annotation)
                 * // 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
                 * withClassAnnotation(final Class<? extends Annotation> annotation)
                 * basePackage(final String basePackage) // 根据包路径扫描接口
                 */
                .apis(RequestHandlerSelectors.basePackage("com.lois.hello"))
                /*
                    配置如何通过path过滤,即这里只扫描请求以/开头的接口
                    any() // 任何请求都扫描
                    none() // 任何请求都不扫描
                    regex(final String pathRegex) // 通过正则表达式控制
                    ant(final String antPattern) // 通过ant()控制
                 */
                // .paths(PathSelectors.ant("/"))
                .build();
    }

    //配置文档信息
    private ApiInfo apiInfo() {
        Contact contact = new Contact("", "", "");
        return new ApiInfo(
                "swagger测试", // 标题
                "这是一个swagger测试文档", // 描述
                "1.0", // 版本
                "", // 组织链接
                contact, // 联系人信息（name,url,email）
                "", // 许可
                "", // 许可连接
                new ArrayList<>()// 扩展
        );
    }
    /*配置多个文档（多人合作开发时）
	@Bean
	public Docket docket1(){
	   return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
	}
	@Bean
	public Docket docket2(){
	   return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
	}
	@Bean
	public Docket docket3(){
	   return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
	}
	*/
    /**
     * 将swagger-ui.html 添加 到 resources目录下
     * 防止swagger 404
     * @param registry
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        registry.addResourceHandler("/web_frontend/**").addResourceLocations("classpath:/web_frontend/");
    }
}

4. 在 com.lois.hello 包下编写controller

@Controller
@RequestMapping("/user/user")
public class UserController {

    @GetMapping("/helloworld")
    public void helloworld(){
        return ;
    }

}

5. 运行项目，访问测试 ：http://项目地址/swagger-ui.html
   

• 1.文档信息
• 2.API分组，多个文档时可选择
• 3.接口信息

四、其他

1. 实体配置
   1.1 创建一个实体类

   @ApiModel("用户")
   public class User {
       @ApiModelProperty("用户名")
       public String username;
       @ApiModelProperty("密码")
       public String password;
   }
   

   1.2 将这个类放在接口的返回值上（不在返回值上是不显示的）

   @Controller
   @RequestMapping("/user/user")
   public class UserController {
   
       @GetMapping("/helloworld")
       public User helloworld(){
           return new User();
       }
   }
   

   1.3 查看结果
   
2. 常用注解

Swagger注解	简单说明
@Api(tags = “xxx模块说明”)	作用在模块类上
@ApiOperation(“xxx接口说明”)	作用在接口方法上
@ApiModel(“xxxPOJO说明”)	作用在模型类上：如VO、BO
@ApiModelProperty(value = “xxx属性说明”,hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam(“xxx参数说明”)	作用在参数、方法和字段上，类似@ApiModelProperty

博主文章致力于简单易学，喜欢文章的同学可以点赞支持一下博主！！~~