Swagger简介:
Swagger 是一个规范且完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口,可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义,用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似,Swagger 消除了调用服务时可能会有的猜测。
Swagger 的优势:
支持 API 自动生成同步的在线文档:使用 Swagger 后可以直接通过代码生成文档,不再需要自己手动编写接口文档了,对程序员来说非常方便,可以节约写文档的时间去学习新技术。
提供 Web 页面在线测试 API:光有文档还不够,Swagger 生成的文档还支持在线测试。参数和格式都定好了,直接在界面上输入参数对应的值即可在线测试接口。
- 创建Springboot项目
- 添加Maven依赖:
<!--Swagger2-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<!-- END Swagger2 -->
- 编写配置类
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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* Swagger2 配置类
* @Configuration 让 Spring 容器加载该配置类
* @EnableSwagger2 用于启动 swagger2 , springboot启动类也需要加
*/
@Configuration
@EnableSwagger2
public class Swagger2Config {
/**
* swagger2 启动后,通过createRestApi函数创建Docket的Bean,
* apiInfo() 用来创建该Api的基本信息(这些基本信息会展现在文档页面中)。
* select() 函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现,
* 本例采用指定扫描的包路径来定义,Swagger会扫描该包下所有Controller定义的API,并产生文档内容(除了被@ApiIgnore指定的请求)。
* @return
*/
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)// 指定api类型为swagger2
.apiInfo(apiInfo())// 用于定义api文档汇总信息,下面的apiInfo()
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.springboot_jpa"))//api接口包扫描路径
.paths(PathSelectors.any())// 可以根据url路径设置哪些请求加入文档,忽略哪些请求
.build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("Springboot 中使用Swagger2构建RESTful APIs")//设置文档的标题
.description("springboot学习")// 设置文档的描述
.contact(new Contact("huangwc",
"http://www.baidu.com",
"huangwencon@foxmail.com")) // 联系人信息
.termsOfServiceUrl("http://www.baidu.com")// 网站地址
.version("2.0")// 文档版本号
.build();
}
}
- 注释启动类:@EnableSwagger2
@SpringBootApplication
@EnableSwagger2
public class SpringbootJpaApplication {
public static void main(String[] args) {
SpringApplication.run(SpringbootJpaApplication.class, args);
}
}
- API 接口编写并生成文档
/*
@Api:修饰整个类,描述Controller的作用
tags="说明该类的作用,可以在UI界面上看到的注解,如果tags多个值,会生成多个list"
value="该参数没什么意义,在UI界面上也看不到,所以不需要配置"
@ApiOperation:用在请求的方法上,说明方法的用途、作用
value="说明方法的用途、作用"
notes="方法的备注说明"
@ApiParam:单个参数描述
@ApiModel:用对象来接收参数
@ApiProperty:用对象接收参数时,描述对象的一个字段
@ApiResponse:HTTP响应其中1个描述
@ApiResponses:HTTP响应整体描述
@ApiIgnore:使用该注解忽略这个API
@ApiError :发生错误返回的信息
@ApiImplicitParam:描述一个请求参数,可以配置参数的中文含义,还可以给参数设置默认值
@ApiImplicitParams:描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表
**/
@Controller
@Api(value = "用户接口",tags = {"用户操作接口"})
public class UserController {
@Autowired
private CarategyRepository carategyRepository;
@Autowired
private NewsRepository newsRepository;
@RequestMapping("gotocarategy")
public String gotoaddcarategy(){
return "user/addcarategy";
}
@ApiOperation(value = "增加carategy",notes = "增加carategy")
/*新增carategy*/
@RequestMapping("/addcarategy")
public String add(@RequestParam(name = "carategy") String carategy){
Carategy carategy1 = new Carategy();
carategy1.setCarategy(carategy);
System.out.println(carategy1.getCarategy());
String str = carategy1.getCarategy();
carategyRepository.addCarategy(str);
return "forward:getallcarategy";
}
@ApiOperation(value = "用于方法描述query",notes = "这是用来说明该方法,提示内容")
@ApiImplicitParams({
@ApiImplicitParam(name = "data",value = "字符串数据",dataType = "String",paramType = "path",example = "白居易",required = true,defaultValue = "白居易"),
@ApiImplicitParam(name = "i",value = "int类型",dataType = "int",paramType = "path",example = "666",required = true,defaultValue = "666")
})
/*查询所有carategy类型,返回数据给新闻增加page*/
@RequestMapping("getallcarategy")
public String findallcarategy(Model model){
List<Carategy> list = carategyRepository.findAll();
model.addAttribute("carategylist",list);
return "user/addnews";
}
}
启动Springboot项目,访问http://ip:端口/swagger-ui.html就可以看到swagger2生成的文档了。