Swagger
一个接口文档工具,可以自动直接扫描写的所有接口,并且支持调试。
1、新建 Springboot 项目
2、编写 HelloWord(新建一个 controller,新建一个 HelloControl.java)
@RestController
public class HelloController {
@GetMapping ("/hello")
public String hello() {
return "hello";
}
}
启动访问 localhost:8080/hello
3、导入 Swagger 依赖(pom.xml)
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
4、编写 SwaggerConfig(新建一个 config,创建 SwaggerConfig.java配置类)
@Configuration
@EnableSwagger2 //开启 Swagger2
public class SwaggerConfig {}
5、访问Swagger 主界面
http://localhost:8080/swagger-ui.html
6、 SwaggerConfig
package swagger.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.PathSelectors;
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;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
//配置多个文档分组
// @Bean
// public Docket docket1() {
// return new Docket(DocumentationType.SWAGGER_2).groupName("A");
// }
//配置了Swagger的Docket的bean实例
@Bean
public Docket docket(Environment environment) {
//设置需要显示的Swagger的环境比如dev ,test, pro 环境
Profiles profiles = Profiles.of("dev");
//通过environment.acceptsProfiles判断是都在当前自己设置的环境中
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
//在自己的环境中,true就启动Swagger
.enable(flag)
.groupName("tong")
.apiInfo(apiInfo())
.select()
//RequestHandlerSelectors:配置要扫描接口的方式
//basePackage:指定要扫描的包
// ==========一般只用basePackage=======
//any():扫描所有
//none():全部不扫描
//withClassAnnotation(Controller.class):用反射的方式扫描类上有@Controller注解的
//withMethodAnnotation(RequestMapping.class):用反射的方式扫描类上有@RequestMapping注解的
//扫描 swagger.controller下的接口
.apis(RequestHandlerSelectors.basePackage("swagger.controller"))
// 配置如何通过path过滤,即这里只扫描请求以/hello开头的接口
// .paths(PathSelectors.ant("/hello/**"))
.build();
}
public ApiInfo apiInfo() {
//作者信息
Contact DEFAULT_CONTACT = new Contact("TomYe", "https://blog.csdn.net/Xiao_tongtong?spm=1010.2135.3001.5421", "519395917@qq.com");
return new ApiInfo(
"TomYe的Swagger",
"一个人走的快",
"v1.0",
"urn:tos",
DEFAULT_CONTACT,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
Swagger常用注解:
作用都是在文档上注释来解释各个接口属性的意思
注解在Controller类上
@Api(tags = "用户登录接口")
注解在方法上面
@ApiOperation("登录方法")
注解在实体类上
//给实体类注释别名
@ApiModel("用户实体类")
注解在实体类属性上
//给字段注释别名
@ApiModelProperty("微信昵称")
tips: 实体类不是通过注解的方式扫描到的,
而是通过配置类里面扫描 Swagger.controller的所有接口,
只要接口中有返回的实体类,那么该实体就会被扫描到。
总结:
- 导依赖 + 配置 swagger + 写注解
- 重点:一定要设置 Swagger 接口文档的显示环境,否则他人可以访问到!