swagger3简单使用
swagger优点：
- 我们可以通过Swagger给一-些比较难理解的属性或者接口， 增加注释信息
- 接口文档实时更新
- 可以在线测试
使用：
1、导入依赖
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>3.0.0</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>3.0.0</version>
</dependency>
//第三方的ui，可以在上面的官方版中选择使用
<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/swagger-bootstrap-ui -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
<!-- 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、swagger配置
package cn.laoyao.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
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;
import java.util.ArrayList;
import static springfox.documentation.service.ApiInfo.DEFAULT_CONTACT;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("A");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("B");
}
//配置swaggerbean实例 每个Bean都是一个分组
@Bean
public Docket docket(Environment environment) {
//设置要显示的swagger环境
Profiles profiles = Profiles.of("dev", "test");
//通过environment.acceptsProfiles判断是否处在自己设置的环境中
boolean b = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//分组
.groupName("老妖")
//是否启用swagger
.enable(b)
.select()
//RequestHandlerSelectors,配置要扫描接口的方式
//basePackage:指定要扫描的包
//any():扫描全部
//none():不扫描
//withClassAnnotation:扫描类上的注解，参数是一个注解的反射对象
//withMethodAnnotation:扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("cn.laoyao.controller"))
.build();
}
// 前台API信息 配置swagger信息 也就是展示用的
private ApiInfo apiInfo(){
//作者信息
Contact contact = new Contact("laoyao", "https://www.cnblogs.com/zlaoyao/", "laoyao.play@outlook.com");
return new ApiInfo("老妖的swagger",
"啦啦啦啦啦绿",
"1.0",
"urn:tos",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
3、使用swaggerUI网站
官方网站：
访问 http://localhost:端口号/swagger-ui/index.html
第三方：
http://localhost:端口号/doc.html
4、还可以给实体类加上注解，使其在swagger中更加易读
@Data
@AllArgsConstructor
@NoArgsConstructor
//模块信息
@ApiModel("用户")
public class User {
//属性信息
@ApiModelProperty("姓名")
private String username;
private String pwd;
}
5、Controller
//api
@Api(value = "用户接口")
@RestController
public class LoginController {
@Resource
private AdminService adminService;
//接口信息
@ApiOperation(value = "login",notes = "登录")
@PostMapping("/user/login")
public ResponseResult login(@RequestBody AdminLoginParam adminLoginParam){
return adminService.login(adminLoginParam);
}
}
6、添加授权信息（如Token）
//配置swaggerbean实例 每个Bean都是一个分组
@Bean
public Docket docket(Environment environment) {
//设置要显示的swagger环境
Profiles profiles = Profiles.of("dev", "test");
//通过environment.acceptsProfiles判断是否处在自己设置的环境中
// boolean b = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//分组
.groupName("老妖")
//是否启用swagger
.enable(true)
.select()
// RequestHandlerSelectors,配置要扫描接口的方式
// basePackage:指定要扫描的包
// any():扫描全部
// none():不扫描
// withClassAnnotation:扫描类上的注解，参数是一个注解的反射对象
// withMethodAnnotation:扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("cn.laoyao.server.controller"))
.build()
.securitySchemes(securitySchemes())
.securityContexts(securityContexts());
}
/**
* 设置授权信息
*/
private List<SecurityScheme> securitySchemes() {
ApiKey apiKey = new ApiKey("BASE_TOKEN", "token", In.HEADER.toValue());
return Collections.singletonList(apiKey);
}
/**
* 授权信息全局应用
*/
private List<SecurityContext> securityContexts() {
return Collections.singletonList(
SecurityContext.builder()
.securityReferences(Collections.singletonList(new SecurityReference("BASE_TOKEN", new AuthorizationScope[]{new AuthorizationScope("global", "")})))
.build()
);
}
7、携带公共请求参数
不同的架构可能发请求的时候除了携带TOKEN，还会携带不同的参数，比如请求的平台，版本等等，这些每个请求都要携带的参数称之为公共参数。
那么如何在Swagger中定义公共的参数呢？比如在请求头中携带。
在Docket中的方法globalRequestParameters()可以设置公共的请求参数，接收的参数是一个List<RequestParameter>，因此只需要构建一个RequestParameter集合即可，如下：
@Bean
public Docket frontApi() {
//构建一个公共请求参数platform，放在在header
RequestParameter parameter = new RequestParameterBuilder()
//参数名称
.name("platform")
//描述
.description("请求的平台")
//放在header中
.in(ParameterType.HEADER)
//是否必传
.required(true)
.build();
//构建一个请求参数集合
List<RequestParameter> parameters = Collections.singletonList(parameter);
return new Docket(DocumentationType.OAS_30)
.....
.build()
.globalRequestParameters(parameters);
}
以上配置完成，将会在每个接口中看到一个请求头，如下图：
参考：
