一、springboot集成Swagger 2.0+
1、导入依赖
</dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency>
2、配置Swagger 编写Config文件
2.1 配置接口扫描与作者信息
使用Dokcet对象中的 .select()方法
@Configuration //表明这是一个配置类 @EnableSwagger2 //开启Swagger2 public class SwaggerConfig { @Value("${spring.swagger.enable}") private Boolean enableSwagger; @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .groupName("James") //API分组 .select() .apis(RequestHandlerSelectors.basePackage("com.it.es.web")) .paths(PathSelectors.ant("/hello/**")) // 可以根据url路径设置哪些请求加入文档，忽略哪些请求 .build();//构建者模式 } /** * 配置Swagger信息 apiinfo * @return */ private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("单词计数服务") //设置文档的标题 .description("单词计数服务 API 接口文档") // 设置文档的描述 .version(VERSION) // 设置文档的版本信息-> 1.0.0 Version information .termsOfServiceUrl("http://www.baidu.com") // 设置文档的License信息->1.3 License information .build();
2.2 配置是否自动启动Swagger
在开发环境开启SwaggerUI ，生产环境关闭SwaggerUI 是因为开发环境是内部人员，生产环境是客户。为了程序的安全性需要关闭SwagggerUI
/** * 配置了Swagger 的Docket的bean实例,扫描接口的位置 * .apis * RequestHandlerSelectors 配置swagger扫描接口的方式 * basePackage() 指定要扫描哪些包 * any() 全部都扫描 * none() 全部不扫描 * withClassAnnotation() 扫描类上的注解 参数是一个注解的反射对象 * withMethodAnnotation() 扫描包上的注解 * .paths * PathSelectors 路径扫描接口 * ant 配置以xxx 开头的路径 * @return */ @Bean public Docket docket(Environment environment){ //设置要显示的Swagger 环境 Profiles profiles =Profiles.of("dev","test"); /** * 通过 environment.acceptsProfiles 返回的boolean值判断是否处在自己所设定的环境中 */ boolean flag = environment.acceptsProfiles(profiles); System.out.println(flag); return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .groupName("James") //.enable(flag) //enable配置是否自动启动swagger 如果为False则为不启动，浏览器中不能访问Swagger .select() .apis(RequestHandlerSelectors.basePackage("com.study.swagger.controller")) //.paths(PathSelectors.ant("/hello/**")) .build();//构建者模式 } /** * 配置Swagger信息 apiinfo * @return */ private ApiInfo apiInfo(){ //配置作者信息 Contact DEFAULT_CONTACT = new Contact("James", "https://blog.csdn.net/zhanshixiang/", "zhanshixiang1997@163.com"); return new ApiInfo( "James 的Swagger API文档", "码出高效", "v1.0", "https://blog.csdn.net/zhanshixiang/", DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList()); }
创建三个properties文件
application.properties
激活开发环境
2.3 配置API分组
/** * 开发A组的接口 * @return */ @Bean public Docket docketA(){ return new Docket(DocumentationType.SWAGGER_2) .groupName("A"); } /** * 开发B组的接口 * @return */ @Bean public Docket docketB(){ return new Docket(DocumentationType.SWAGGER_2) .groupName("B"); } /** * 开发C组的接口 * @return */ @Bean public Docket docketC(){ return new Docket(DocumentationType.SWAGGER_2) .groupName("C"); }
2.4 配置实体类信息和接口方法
配置实体类信息
@ApiModel("用户实体类") public class User implements Serializable { @ApiModelProperty("用户名") private String username; @ApiModelProperty("密码") private String password;
配置接口方法
@Api("Hello控制类") @RestController @RequestMapping("hello") public class HelloController { @GetMapping(value = "say") public String hello() { return "hello "; } /** * 只要接口中,返回值中存在实体类，他就会被扫描到Swagger中 * @return */ @PostMapping(value = "/user") public User user(){ return new User(); } /** * ApiOperation接口，不是放在类上的，是方法 * @return */ @ApiOperation("hello控制类") @GetMapping(value = "/hello2") public String hello2(@ApiParam("用户名") String username){ return "hello"+username; } @ApiOperation("Post测试类") @PostMapping(value = "/post") public User post(@ApiParam("用户") User user){ return user; } }
二、 SpringBoot整合Swagger3.0+
官方文档 http://springfox.github.io/springfox/docs/current/
简介
Swagger3在Swagger2的基础上进行了部分升级，与swagger2相比新版的swagger3配置更少，使用更加方便。 一个重要的优化是依赖的引入，由之前的多个依赖变更为一个依赖，跟随springboot-starter风格，同时引入了新的开关注解@EnableOpenApi 以代替@EnableSwagger2 。 因此，集成工作变得更加的简便了，必要工作只有两个，添加swagger3的starter依赖包，在springboot主程序类添加@EnableOpenApi开关注解。
1、快速入门
1.1 引入依赖
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency>
2.2 启动类添加开关注解@EnableOpenApi
作用：表示开启生成接口文档功能，只有开启了OpenApi，才能实现生成接口文档的功能
@EnableOpenApi @SpringBootApplication public class SwaggerApplication { public static void main(String[] args) { SpringApplication.run(SwaggerApplication.class, args); } }
2.3 配置Swagger配置文件
// 表明当前类是配置类 @Configuration public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.OAS_30) .apiInfo(apiInfo()) .select()// 为api选择启动生成器 //RequestHandlerSelectors,配置要扫描接口的方式 //basePackage:指定要扫描的包 //any()：扫描全部 //none():不扫描 //.withClassAnnotation():扫描类上的注解 //.withMethodAnnotation():扫描方法上的注解 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))// 指定要生成api文档的根包 .paths(PathSelectors.any())// 路径配置 .build(); } /** * 创建一个ApiInfo对象 * * @return */ private ApiInfo apiInfo() { return new ApiInfoBuilder() // 文档标题 .title("SpringBoot整合Swagger3") // 简介 .description("更多请咨询服务开发者小龍") // 作者信息：作者姓名、作者地址、作者邮箱 .contact(new Contact("小龍", "https://blog.csdn.net/wangzhilong1996", "123456@qq.com")) // 版本号 .version("1.0") .build(); } }
2.4 配置实体类信息和接口方法
和swagger 2.X一样
2.5 引入第三方UI包
原生的ui页面并不美观，我们可以选择使用第三方的ui包来美化页面，当然，市面上的第三方ui包有很多，大家可以找一个自己喜欢的，不一定用我的。
<!-- swagger 第三方ui包 --> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.9.6</version> </dependency>
2.6 访问地址
swagger3跟swagger2访问地址有所区别 ：swagger3的地址是 http://localhost:8080/swagger-ui/
2.7 如果报错404
package com.jdwifi.g1335333249.config; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.EnableWebMvc; import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport; @EnableWebMvc @Configuration public class WebConfig extends WebMvcConfigurationSupport { @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("/**").addResourceLocations( "classpath:/static/"); registry.addResourceHandler("swagger-ui.index.html").addResourceLocations( "classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**").addResourceLocations( "classpath:/META-INF/resources/webjars/"); super.addResourceHandlers(registry); } }
2.8 从现有 2.x 版本迁移 3.X版本
上述说明其实在swagger官网有说，但是大部分人不看而已，所以给出链接：如何从swagger老版本迁移到3.0.0
Spring Boot 应用程序
注意：希望得到反馈以使其更好
删除显式依赖 springfox-swagger2
删除@EnableSwagger2注释
添加springfox-boot-starter依赖
Springfox 3.x 移除了对 guava 和其他 3rd 方库的依赖（还不是零依赖！依赖于 spring 插件和用于注释和模型的开放 api 库）所以如果你使用了 guava 谓词/函数，这些将需要转换到 java 8 函数接口
如果您正在使用 WebMvc 但您还没有使用该@EnableWebMvc注解，请添加此注解。
拓展
1、@EnableOpenApi注解到底是什么作用，尝试不加该注解，仍谈可以正常生成文档
2、如何在项目中实现不将swagger应用到生产环境中去
