注意：jdk 1.8以上才能运行swagger2
1、导入jar包依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
<exclusions>
<exclusion>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.5.22</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2、通过配置类配置 Swagger
package com.dgood.cms.config;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.Map;
//配置类注解
@Configuration
//开启swagger2
@EnableSwagger2
//读取application.properties中的swagger.config 配置
@ConfigurationProperties("swagger.config")
@Data
public class SwaggerConfig {
//swagger cms的配置
private Map<String, String> cms;
//swagger weixin的配置
private Map<String, String> weixin;
//创建cms的swagger
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName(cms.get("groupName")).enable("1".equals(cms.get("enable")) ? true : false)
.select()
.apis(RequestHandlerSelectors.basePackage(cms.get("basePackage")))
.paths(PathSelectors.any()).build();
}
//创建weixin的swagger
@Bean
public Docket createWeiXinRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(weixinApiInfo()) //swagger2 配置
.groupName(weixin.get("groupName")) //设置分组名称
.enable("1".equals(weixin.get("enable")) ? true : false)//是否开启swagger 如果是false 则通过swagger-ui.html 访问不到
.select()
.apis(RequestHandlerSelectors.basePackage(weixin.get("basePackage"))) // 设置swagger2扫描包
.paths(PathSelectors.any()).build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title(cms.get("title")) //swagger标题
.description(cms.get("description"))// 描述
.version(cms.get("version"))//版本
.build();
}
private ApiInfo weixinApiInfo() {
return new ApiInfoBuilder()
.title(weixin.get("title"))
.description(weixin.get("description"))
.version(weixin.get("version"))
.build();
}
}
application.properties 中swagger配置信息
#swagger 配置
swagger.config.cms.enable=1
swagger.config.cms.groupName=CMS
swagger.config.cms.title=CMS API 文档
swagger.config.cms.description=CMS接口文档
swagger.config.cms.version=v1.0.0
swagger.config.cms.basePackage=com.dgood.cms.controller
swagger.config.weixin.enable=1
swagger.config.weixin.groupName=微信
swagger.config.weixin.title=WeiXin API 文档
swagger.config.weixin.description=微信接口文档
swagger.config.weixin.version=v1.0.0
swagger.config.weixin.basePackage=com.dgood.weixin.controller
通过以上的配置swagger2就配置成功了
访问http://localhost:8086/swagger-ui.html则可以看下swagger2页面
swagger-ui.html 分为以上4个部分
第一部分--API分组：如果没有配置分组默认是default。通过Swagger实例Docket的groupName()方法即可配置分组
第二部分--基本描述：可以通过Swagger实例Docket的apiInfo()方法中的ApiInfo实例参数配置文档信息
第三部分--请求接口列表：在组范围内，只要被Swagger2扫描匹配到的请求都会在这里出现。
第四部分--实体列表：只要实体在请求接口的返回值上（即使是泛型），都能映射到实体项中！
第一部分：配置API分组
API分组通过configuration 中的进行配置
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName(cms.get("groupName")).enable("1".equals(cms.get("enable")) ? true : false)
.select()
.apis(RequestHandlerSelectors.basePackage(cms.get("basePackage")))
.paths(PathSelectors.any()).build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title(cms.get("title")) //swagger标题
.description(cms.get("description"))// 描述
.version(cms.get("version"))//版本
.build();
}
如果想配置多个分组则配置多个Docket即可
Swagger2的常用注解
Controller 上配置
@Api(tags ="用户操作", value ="用户")
@RequestMapping("/user")
@RestController
public class UserController {
@ApiOperation(value ="用户登录")
@ApiImplicitParams({
@ApiImplicitParam(name ="username", value ="用户名", required =true, dataType ="String"),
@ApiImplicitParam(name ="password", value ="密码", required =true, dataType ="String")
})
@ApiResponses({
@ApiResponse(code =1, message ="登录成功"),
@ApiResponse(code =2, message ="登录失败")
})
@PostMapping({"/login"})
public Stringlogin(String username, String password) {
if ("admin".equals(username) &&"admin".equals(password)) {
HttpServletRequest request = ((ServletRequestAttributes) RequestContextHolder.getRequestAttributes()).getRequest();
request.getSession().setAttribute("user", username);
return "1";
}else {
return "2";
}
}
}
model实体配置
@Data
@Slf4j
@ApiModel(value="用户实体类",description ="用户")
public class User {
@ApiModelProperty(value ="id",example ="1")
private Longid;
@ApiModelProperty(value ="用户名",example ="admin")
private Stringusername;
@ApiModelProperty(value ="密码",example ="password")
private Stringpassword;
}
最终效果
