Swagger简介
世界上最流行的API工具Swagger是世界上最大的框架API开发工具的API规范(OAS),使整个API开发生命周期,从设计、文档、测试和部署。Swagger官网:https://swagger.io/。
1、什么是Swagger?
Swagger是一组围绕OpenAPI规范构建的开源工具,可帮助设计、构建、记录和使用REST API。
2、什么是OpenAPI?
OpenAPI规范就是REST API的API描述格式。OpenAPI文件允许描述整个API包括:
‧/user 每个端点(GET/users,POST/users)上的可用端点和操作
‧操作参数每个输入和输出
‧认证方式
‧联系信息、许可证、及其它信息
API规范可以用YAML或JSON编写,这种格式对于人们和机器都是易于学习和可读的。
Swagger集成SpringBoot
可以去springboot官网:http://projects.spring.io/spring-boot/下载一个简易的spring boot的项目也可以自己创建。
1、pom.xml文件添加Maven依赖。
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
2、添加SwaggerConfig配置
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;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.pathMapping("/")
.select()
.apis(RequestHandlerSelectors.basePackage("暴露接口地址的包路径"))
.paths(PathSelectors.any())
.build()
.apiInfo(testApiInfo());
}
private ApiInfo testApiInfo() {
return new ApiInfoBuilder()
.title("springboot利用swagger构建api文档")//标题
.description("详细描述")//详细描述
.version("1.0")//版本
.termsOfServiceUrl("NO terms of service")
.contact("nice")//作者
.license("The Apache License, Version 2.0")
.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
.build();
}
}
3、需要暴露的接口代码作为参考
import com.rqbao.comm.model.User;
import com.rqbao.service.UserService;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping(value = "/user")
public class SwaggerController {
@Autowired
UserService userService;
@ApiOperation(value = "查询用户",notes = "根据UserId对象查询")
@ApiImplicitParam(name = "userId",value = "id", required = true,dataType = "Long",paramType = "path")
@RequestMapping(method = RequestMethod.GET , value = "{id}")
public User findById(@PathVariable("id") Long id){
return userService.findById(id);
}
@ApiOperation(value = "添加用户",notes = "根据User对象添加")
@ApiImplicitParam(name = "user", value = "user", required = true, dataType = "User")
@RequestMapping(method = RequestMethod.GET , value = "add")
public User insert(){
User user = new User();
user.setUserName("nice");
user.setJob("java");
return userService.insert(user);
}
}
4、访问http://localhost:9001/swagger-ui.html,效果如下。swagger会将接口以WEB形式展现给我们并且提供测试及API文档。(9001可根据自己端口更改)