SpringBoot整合swagger
什么是swagger
官网有这么一段话:The OpenAPI specification (formerly known as the Swagger Specification) is a powerful definition format to describe RESTful APIs. The specification creates a RESTful interface for easily developing and consuming an API by effectively mapping all the resources and operations associated with it. It’s easy-to-learn, language agnostic, and both human and machine readable.
翻译:OpenAPI规范(以前称为Swagger Specification)是用于描述RESTful API的强大定义格式。 该规范创建了一个RESTful接口,通过有效地映射与其关联的所有资源和操作,轻松开发和使用API。 它易于学习,语言不可知,并且人机可读。
Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。
使用swagger的好处
它是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。如何使用swagger
步骤一:pom文件中导入swagger依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>
步骤二:创建swagger配置文件
/**
* swagger2配置类,生成RESTful API生成文档
* 常用注解:
* API 作用在类上,给类添加说明
* ApiOperation 给API增加说明、作用在方法上
* ApiImplicitParams 给多个参数增加说明
* ApiImplicitParam 给一个参数增加说明。
* ApiParam 给方法的参数作说明
*
* ApiOperation和@ApiParam为添加的API相关注解,个参数说明如下:
* ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”;
* ApiParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”
*/
@Configuration //标注配置类,框架读取
@EnableSwagger2 //启动swagger2
public class SwaggerConfig {
/**
* 再通过createRestApi函数创建Docket的Bean之后,apiInfo()用来创建该Api的
* 基本信息(这些基本信息会展现在文档页面中)。select()函数返回一个
* ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现,本例采用指
* 定扫描的包路径来定义,Swagger会扫描该包下所有Controller定义的API,并
* 产生文档内容(除了被@ApiIgnore指定的请求)。
*
* @return
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("xxx.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTful APIs")
.description("swagger2-可视化API文档,方便开发调试")
.termsOfServiceUrl("http://www.baidu.com/")
.contact("xxx")
.version("1.0")
.build();
}
}
步骤三:在对应的controller中添加swagger的注解,自动生成API
@RestController
@RequestMapping("users")
@Api(value="User-Controller",description = "用户") // 给类添加说明
public class UserController {
@Autowired
private IUserService userService;
@ApiOperation(value = "获取所有用户列表",httpMethod = "GET",produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
@RequestMapping(value = "list", method = RequestMethod.GET)
public List<User> list() {
return userService.getAll();
}
@ApiOperation(value = "更新用户", httpMethod = "PUT", response = User.class ,notes = "")
@PutMapping("/{id}")
public String updateUser(@ApiParam(required = true, name="用户id", value="")@PathVariable(value="id",required = true) Long id,
@ApiParam(required = true, name="用户对象", value="")@ModelAttribute User user){
User u = users.get(id);
u.setName(user.getName());
u.setAge(user.getAge());
users.put(u.getId(),u);
return "success";
}
结果展示:
常用注解:
- @Api()用于类;
表示标识这个类是swagger的资源
- @ApiOperation()用于方法;
表示一个http请求的操作
- @ApiParam()用于方法,参数,字段说明;
表示对参数的添加元数据(说明或是否必填等)