Swagger

1.swagger介绍

 

现在开发，很多采用前后端分离的模式，前端只负责调用接口，进行渲染，前端和后端的唯一联系，变成了API接口。因此，API文档变得越来越重要。swagger是一个方便我们更好的编写API文档的框架，而且swagger可以模拟http请求调用。

 

大部分采取的方式：Vue + SpringBoot，Vue通过js渲染页面，后端把数据传递给js，早期前端只负责写页面，然后把写好的HTML页面给后端，后端使用模板引擎（Jsp，Thymeleaf、 freemarker）进行开发。

 

前后端分离的好处：各自开发，相对独立，松耦合，前后端通过API进行交互，后端提供接口给前端，前端去调用该接口，但可能会导致前后端团队人员不能做到及时协商，出现一些问题。解决方式：早期使用实时更新文档，但非常繁琐，后来又使用postman来进行一些测试。

 

swagger是目前最流行的Api框架，官网：https://swagger.io/

 

2.springboot中集成swagger使用步骤：

 

导入依赖

<dependency> <groupId>io.springfox</groupId>   <artifactId>springfox-swagger-ui</artifactId>   <version>2.9.2</version>   </dependency>   <dependency> <groupId>io.springfox</groupId>   <artifactId>springfox-swagger2</artifactId>   <version>2.9.2</version>   </dependency>

 

创建配置类

@Configuration @EnableSwagger2//开启Swagger2 public class SwaggerConfig { }

 

然后启动测试运行，访问：http://localhost:8080/swagger-ui.html，看到如下页面：

手动配置实例，修改SwaggerConfig配置类

package com.qf.swagger.config; 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//开启Swagger2 public class SwaggerConfig { //配置Swagger的Bean实例 @Bean public Docket swaggerSpringMvcPlugin() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()); } //配置API的基本信息（会在http://项目实际地址/swagger-ui.html页面显示） private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("测试API文档标题") .description("测试api接口文档描述") .termsOfServiceUrl("http://www.baidu.com") .version("1.0") .build(); } }

 

 

 

 

然后再次重启测试运行：

创建实体类

package com.qf.swagger.entity; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; @ApiModel("用户实体类") public class User { @ApiModelProperty("用户名") private String username; @ApiModelProperty("密码") private String password; public String getUsername() { return username; } public void setUsername(String username) { this.username = username; } public String getPassword() { return password; }   public void setPassword(String password) {   this.password = password; } }

 

创建controller

package com.qf.swagger.controller; import com.qf.swagger.entity.User; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; @Api(description ="用户管理API") @RestController public class UserController { @ApiOperation("添加用户") @PostMapping("/add") public User add(@ApiParam("用户名") String username,@ApiParam("密码") String password){ return new User(); } @ApiOperation("修改用户") @PostMapping("/update") public String update(){ return "修改"; } @ApiOperation("删除用户") @GetMapping("/delete") public Boolean delete(@ApiParam("用户编号") Integer id){ return true;   } @ApiOperation("查询用户") @RequestMapping("/query") public User query(){ User user = new User(); user.setUsername("jack"); user.setPassword("1234"); return user; } }

 

修改SwaggerConfig配置类

package com.qf.swagger.config; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; 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//开启Swagger2 public class SwaggerConfig { //配置Swagger的Bean实例   @Bean   public Docket swaggerSpringMvcPlugin() {   return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo())   .groupName("yangl")//分组名称(可以创建多个Docket就有多个组名) .enable(true)//enable表示是否开启Swagger .select() //RequestHandlerSelectors指定扫描的包 .apis(RequestHandlerSelectors.basePackage("com.qf.swagger.controller"))   .build(); } //配置API的基本信息（会在http://项目实际地址/swagger-ui.html页面显示） private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("测试API文档标题") .description("测试api接口文档描述") .termsOfServiceUrl("http://www.baidu.com") .version("1.0") .build(); } }

 

 

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息

 

@Api：修饰整个类，描述Controller的作用

@ApiOperation：描述一个类的一个方法，或者说一个接口

@ApiModel：用对象来接收参数 ，修饰类

@ApiModelProperty：用对象接收参数时，描述对象的一个字段

@ApiResponse：HTTP响应其中1个描述

@ApiResponses：HTTP响应整体描述，一般描述错误的响应

@ApiIgnore：使用该注解忽略这个API

@ApiError ：发生错误返回的信息

@ApiParam：单个参数描述

@ApiImplicitParam：一个请求参数，用在方法上

@ApiImplicitParams：多个请求参数