一:swagger介绍
相信无论是前端还是后端开发,都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力,经常来不及更新。其实无论是前端调用后端,还是后端调用后端,都期望有一个好的接口文档。但是这个接口文档对于程序员来说,就跟注释一样,经常会抱怨别人写的代码没有写注释,然而自己写起代码起来,最讨厌的,也是写注释。所以仅仅只通过强制来规范大家是不够的,随着时间推移,版本迭代,接口文档往往很容易就跟不上代码了。
使用Swagger你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具,就可以做到生成各种格式的接口文档,生成多种语言的客户端和服务端的代码,以及在线接口调试页面等等。这样,如果按照新的开发模式,在开发新版本或者迭代版本的时候,只需要更新Swagger描述文件,就可以自动生成接口文档和客户端服务端代码,做到调用端代码、服务端代码以及接口文档的一致性。
为了简化swagger的使用,Spring框架对swagger进行了整合,建立了Spring-swagger项目,后面改成了现在的Springfox。通过在项目中引入Springfox,可以扫描相关的代码,生成描述文件,进而生成与代码一致的接口文档和客户端代码。
Springfox对应的maven坐标如下:
<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>
二:swagger常用API介绍
注解 | 说明 |
---|---|
@Api | 用在请求的类上,例如Controller,表示对类的说明 |
@ApiModel | 用在类上,通常是实体类,表示一个返回响应数据的信息 |
@ApiModelProperty | 用在属性上,描述响应类的属性 |
@ApiOperation | 用在请求的方法上,说明方法的用途、作用 |
@ApiImplicitParams | 用在请求的方法上,表示一组参数说明 |
@ApiImplicitParam | 用在@ApiImplicitParams注解中,指定一个请求参数的各个方面 |
三:swagger案例
第一步:创建maven工程swagger_demo并配置pom.xml文件
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"><modelVersion>4.0.0</modelVersion><parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>2.2.2.RELEASE</version><relativePath/></parent><groupId>cn.itcast</groupId><artifactId>swagger_demo</artifactId><version>0.0.1-SNAPSHOT</version><name>swagger_demo</name><description>Demo project for Spring Boot</description><properties><java.version>1.8</java.version></properties><dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><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><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId></dependency></dependencies>
</project>
第二步:创建application.yml文件
server:port: 9000
第三步: 创建实体类User和Menu
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;@Data
@ApiModel(description = "用户实体")
public class User {@ApiModelProperty(value = "主键")private int id;@ApiModelProperty(value = "姓名")private String name;@ApiModelProperty(value = "年龄")private int age;@ApiModelProperty(value = "地址")private String address;
}
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;@Data
@ApiModel(description = "菜单实体")
public class Menu {@ApiModelProperty(value = "主键")private int id;@ApiModelProperty(value = "菜单名称")private String name;
}
第四步:创建UserController和MenuController
import cn.itcast.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import java.util.ArrayList;
import java.util.List;@RestController
@RequestMapping("/user")
@Api(tags = "用户控制器")
public class UserController {@GetMapping("/getUsers")@ApiOperation(value = "查询所有用户", notes = "查询所有用户信息")public List<User> getAllUsers(){User user = new User();user.setId(100);user.setName("itcast");user.setAge(20);user.setAddress("bj");List<User> list = new ArrayList<>();list.add(user);return list;}@PostMapping("/save")@ApiOperation(value = "新增用户", notes = "新增用户信息")public String save(@RequestBody User user){return "OK";}@PutMapping("/update")@ApiOperation(value = "修改用户", notes = "修改用户信息")public String update(@RequestBody User user){return "OK";}@DeleteMapping("/delete")@ApiOperation(value = "删除用户", notes = "删除用户信息")public String delete(int id){return "OK";}@ApiImplicitParams({@ApiImplicitParam(name = "pageNum", value = "页码", required = true, type = "Integer"),@ApiImplicitParam(name = "pageSize", value = "每页条数", required = true, type = "Integer"),})@ApiOperation(value = "分页查询用户信息")@GetMapping(value = "page/{pageNum}/{pageSize}")public String findByPage(@PathVariable Integer pageNum,@PathVariable Integer pageSize) {return "OK";}
}
import cn.itcast.entity.Menu;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import java.util.ArrayList;
import java.util.List;@RestController
@RequestMapping("/menu")
@Api(tags = "菜单控制器")
public class MenuController {@GetMapping("/getMenus")@ApiOperation(value = "查询所有菜单", notes = "查询所有菜单信息")public List<Menu> getMenus(){Menu menu = new Menu();menu.setId(100);menu.setName("itcast");List<Menu> list = new ArrayList<>();list.add(menu);return list;}@PostMapping("/save")@ApiOperation(value = "新增菜单", notes = "新增菜单信息")public String save(@RequestBody Menu menu){return "OK";}@PutMapping("/update")@ApiOperation(value = "修改菜单", notes = "修改菜单信息")public String update(@RequestBody Menu menu){return "OK";}@DeleteMapping("/delete")@ApiOperation(value = "删除菜单", notes = "删除菜单信息")public String delete(int id){return "OK";}@ApiImplicitParams({@ApiImplicitParam(name = "pageNum", value = "页码", required = true, type = "Integer"),@ApiImplicitParam(name = "pageSize", value = "每页条数", required = true, type = "Integer"),})@ApiOperation(value = "分页查询菜单信息")@GetMapping(value = "page/{pageNum}/{pageSize}")public String findByPage(@PathVariable Integer pageNum,@PathVariable Integer pageSize) {return "OK";}
}
第五步:创建配置类SwaggerAutoConfiguration
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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration
@EnableSwagger2
public class SwaggerAutoConfiguration {@Beanpublic Docket createRestApi1() {Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("用户接口组").select()//为当前包路径.apis(RequestHandlerSelectors.basePackage("cn.itcast.controller.user")).build();return docket;}@Beanpublic Docket createRestApi2() {Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("菜单接口组").select()//为当前包路径.apis(RequestHandlerSelectors.basePackage("cn.itcast.controller.menu")).build();return docket;}//构建 api文档的详细信息private ApiInfo apiInfo() {return new ApiInfoBuilder()//页面标题.title("API接口文档")//创建人.contact(new Contact("dlwlrma晴子", "http://www.dlwlrma.com", ""))//版本号.version("1.0")//描述.description("API 描述").build();}
}
第六步:创建启动类SwaggerDemoApplication
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;@SpringBootApplication
public class SwaggerDemoApplication {public static void main(String[] args) {SpringApplication.run(SwaggerDemoApplication.class, args);}
}
执行启动类main方法启动项目,访问地址:http://localhost:9000/swagger-ui.html