注意：jdk 1.8以上才能運(yùn)行swagger2
1、導(dǎo)入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;
//創(chuàng)建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();
? ? }
//創(chuàng)建weixin的swagger
? ? @Bean
? ? public Docket createWeiXinRestApi() {
? ? ? ? return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(weixinApiInfo()) //swagger2 配置
.groupName(weixin.get("groupName")) //設(shè)置分組名稱
.enable("1".equals(weixin.get("enable")) ? true : false)//是否開啟swagger? 如果是false 則通過swagger-ui.html 訪問不到
? ? ? ? ? ? ? ? .select()
? ? ? ? ? ? ? ? .apis(RequestHandlerSelectors.basePackage(weixin.get("basePackage")))? // 設(shè)置swagger2掃描包
? ? ? ? ? ? ? ? .paths(PathSelectors.any()).build();
? ? }
? ? private ApiInfo apiInfo() {
? ? ? ? return new ApiInfoBuilder()
? ? ? ? ? ? ? ? .title(cms.get("title"))? ?//swagger標(biāo)題
? ? ? ? ? ? ? ? .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個(gè)部分
第一部分--API分組：如果沒有配置分組默認(rèn)是default。通過Swagger實(shí)例Docket的groupName()方法即可配置分組
第二部分--基本描述：可以通過Swagger實(shí)例Docket的apiInfo()方法中的ApiInfo實(shí)例參數(shù)配置文檔信息
第三部分--請求接口列表：在組范圍內(nèi)，只要被Swagger2掃描匹配到的請求都會在這里出現(xiàn)。
第四部分--實(shí)體列表：只要實(shí)體在請求接口的返回值上（即使是泛型），都能映射到實(shí)體項(xiàng)中！
第一部分：配置API分組
API分組通過configuration 中的進(jìn)行配置
?@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標(biāo)題
? ? ? ? ? ? ? ? .description(cms.get("description"))// 描述
? ? ? ? ? ? ? ? .version(cms.get("version"))//版本
? ? ? ? ? ? ? ? .build();
? ? }
如果想配置多個(gè)分組則配置多個(gè)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實(shí)體配置
@Data
@Slf4j
@ApiModel(value="用戶實(shí)體類",description ="用戶")
public class User {
@ApiModelProperty(value ="id",example ="1")
private Longid;
? ? @ApiModelProperty(value ="用戶名",example ="admin")
private Stringusername;
? ? @ApiModelProperty(value ="密碼",example ="password")
private Stringpassword;
}
最終效果
