一、Swagger2
1.1、RESTful API
RESTful API：
1.2、Swagger2的API介绍
//应用类 //说明接口文件 @Api(value = "测试接口", tags = "用户管理相关的接口", description = "用户测试接口") //应用方法(一般为方法描述以及参数) //方法描述：value方法名称，notes方法描述 @ApiOperation(value="删除用户", notes="根据url的id来指定删除对象") //单个参数：name参数名；value参数说明，备注；dataType参数类型；required 是否必传；defaultValue 默认值 @ApiImplicitParam(name = "user", value = "新增用户数据") //多参数描写法： @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"), @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User") }) //应用于pojo属性(Model) //描述字段信息 @ApiModelProperty("用户年龄")
1.3、springboot+swagger2使用
1、引入swagger2的坐标
<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>
2、编写Swagger2的配置类：SwaggerConfig.java
@Configuration @EnableSwagger2 //启用Swagger2 public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) //是否开启 (true 开启 false隐藏。生产环境建议隐藏) //.enable(false) .select() //扫描的路径包,设置basePackage会将包下的所有被@Api标记类的所有方法作为api：我这里设置指定的controller包下 .apis(RequestHandlerSelectors.basePackage("xyz.changlu.controller")) //指定路径处理PathSelectors.any()代表所有的路径 .paths(PathSelectors.any()) .build(); } //创建API的基本信息 private ApiInfo apiInfo() { return new ApiInfoBuilder() //设置文档标题(API名称) .title("SpringBoot中使用Swagger2接口规范") //文档描述 .description("接口说明") //服务条款URL .termsOfServiceUrl("http://localhost:8080/") //版本号 .version("1.0.0") .build(); } }
3、编写controller附带user实体类
User.java @Data public class User { @ApiModelProperty("用户id") private Long id; @ApiModelProperty("用户姓名") private String name; @ApiModelProperty("用户年龄") private Integer age; }
UserController.java
@RestController @RequestMapping(value="/users") //1、Api：用来描述类。 @Api(value = "测试接口", tags = "用户管理", description = "用户管理相关接口") public class UserController { static Map<Long, User> users = Collections.synchronizedMap(new HashMap<Long, User>()); @ApiOperation(value="获取用户列表") @RequestMapping(value={""}, method= RequestMethod.GET) public List<User> getUserList() { List<User> r = new ArrayList<User>(users.values()); return r; } //方法作用 @ApiOperation(value="创建用户", notes="根据User对象创建用户") //描述指定属性 @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User") @RequestMapping(value="", method=RequestMethod.POST) public String postUser(@RequestBody User user) { users.put(user.getId(), user); return "success"; } @ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息") @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long") @RequestMapping(value="/{id}", method=RequestMethod.GET) public User getUser(@PathVariable Long id) { return users.get(id); } @ApiOperation(value="更新用户详细信息", notes="根据url的id来指定更新对象，并根据传过来的user信息来更新用户详细信息") //描述多个参数 @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"), @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User") }) @RequestMapping(value="/{id}", method=RequestMethod.PUT) public String putUser(@PathVariable Long id, @RequestBody User user) { User u = users.get(id); u.setName(user.getName()); u.setAge(user.getAge()); users.put(id, u); return "success"; } @ApiOperation(value="删除用户", notes="根据url的id来指定删除对象") @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long") @RequestMapping(value="/{id}", method=RequestMethod.DELETE) public String deleteUser(@PathVariable Long id) { users.remove(id); return "success"; } }
ok，最终访问http://localhost:8080/swagger-ui.html即可！！！
二、swagger3
2.1、springboot整合
注意点：依赖的springboot版本应该为2.5.3，高版本没有对应webmvc模块
<groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.5.3</version>
step1：引入依赖
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency>
step2：开启swagger3
@EnableOpenApi //在springboot启动类上添加
step3：添加配置类
import io.swagger.annotations.ApiOperation; 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; /** * @ClassName Swagger3Config * @Author ChangLu * @Date 2021/9/20 20:55 * @Description TODO */ @Configuration public class Swagger3Config { @Bean public Docket createRestApi() { return new Docket(DocumentationType.OAS_30) .apiInfo(apiInfo()) .select() //扫描的路径包,这里扫描所有带有@ApiOperation注解的方法 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //指定路径处理PathSelectors.any()代表所有的路径 .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() //设置文档标题(API名称) .title("svublog-web接口文档") //文档描述 .description("web接口文档说明") // 作者信息：作者名称、官网、邮箱 .contact(new Contact("Ray。", "http://www.ruiyeclub.cn", "ruiyeclub@foxmail.com")) //文档版本 .version("1.0") .build(); } }
ok，之后启动项目，访问http://localhost:8080/swagger-ui/
2.2、集成第三方UI界面
<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.9.6</version> </dependency>
启动项目访问：http://localhost:8080/doc.html
更加清晰明了
2.3、API介绍
//1、接口类描述 @Api(value = "desc of class") public class HelloController { //2、方法描述 @ApiOperation(value = "hello one", notes = "") @GetMapping(value = "/hello1") //3、单个方法参数描述 public Object hello( /* 参数注解 */ @ApiParam(value = "desc of param", required = true) @RequestParam String name) {
