1. 在pom.xml文件引入Jar包:
<!-- 用于JSON API文档的生成-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!--用于文档界面展示-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2. 配置swagger:
- 在项目新建目录configuration,在目录内创建类SwaggerConfig
package springboot.demo.swagger.configuration;
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* @author Administrator on 2019/10/26.
* @version 1.0
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(new ApiInfoBuilder().title("XXX系统API文档")
.description("XXX系统API接口文档描述")
.version("1.0").build())
.select()
.apis(RequestHandlerSelectors.basePackage("项目基础包名"))
.paths(PathSelectors.any())
.build();
}
}
接下来访问默认http://127.0.0.1:8080/swagger-ui.html地址,就可以访问接口文档地址了
3.添加swagger注解,生成api文档
Controller层:
package springboot.demo.swagger.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;
import springboot.demo.swagger.entity.User;
/**
* @author Administrator on 2019/10/26.
* @version 1.0
*/
@RestController
@RequestMapping("user")
@Api(tags = "用户API接口")
public class UserController {
@GetMapping()
@ApiOperation(value = "查询用户列表数据")
public String list() {
return "查询列表数据!";
}
@GetMapping("{id}")
@ApiOperation(value = "查询单个用户数据", notes = "提示xxxx")
public String find(@ApiParam(name="id",value="用户id",required=true) @PathVariable Integer id) {
return String.format("根据主键查询数据: %d", id);
}
@PostMapping()
@ApiOperation(value = "添加新用户")
public void add(@ApiParam(name="user",value="用户对象",required=true) User user) {
System.out.println("插入数据!");
}
@PutMapping()
@ApiOperation(value = "修改用户")
public void update(@ApiParam(name="user",value="用户对象",required=true) User user) {
System.out.println("修改用户数据");
}
@DeleteMapping("{id}")
@ApiOperation(value = "删除用户")
public String delete(@ApiParam(name="id",value="用户id",required=true) @PathVariable Integer id) {
return String.format("根据主键删除记录: %d", id);
}
}
@Api() 用于类;
表示标识这个类是swagger的资源
tags–表示说明
value–也是说明,可以使用tags替代
@ApiOperation() 用于方法;表示一个http请求的操作
value用于方法描述
notes用于提示内容
tags可以重新分组(视情况而用)
@ApiParam() 用于方法,参数,字段说明;表示对参数的添加元数据(说明或是否必填等)
name–参数名
value–参数说明
required–是否必填
效果图:
实体类层:
package springboot.demo.swagger.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import javax.validation.constraints.Email;
import javax.validation.constraints.NotBlank;
import javax.validation.constraints.Size;
import java.util.Date;
/**
* @author Administrator on 2019/10/26.
* @version 1.0
*/
@Data
@ApiModel(value="user对象",description="user对象描述")
public class User {
/**
* 用户 ID
*/
@ApiModelProperty(name = "id", value = "主键", hidden = true)
private Long id;
/**
* 用户名
*/
@ApiModelProperty(name = "username", value = "用户名", dataType = "string",example = "admin")
@Size(min = 4, max = 10, message = "{range}")
private String username;
/**
* 密码
*/
@ApiModelProperty(name = "password", value = "密码", dataType = "string",example = "123456")
private String password;
/**
* 邮箱
*/
@ApiModelProperty(name = "email", value = "邮箱", dataType = "string",example = "[email protected]")
@Size(max = 50, message = "{noMoreThan}")
@Email(message = "{email}")
private String email;
/**
* 状态 0锁定 1有效
*/
@ApiModelProperty(name = "status", value = "是否有效0=无效,1=有效", dataType="int",example = "1")
@NotBlank(message = "{required}")
private String status;
/**
* 创建时间
*/
@ApiModelProperty(name = "createTime", value = "创建时间", hidden = true)
private Date createTime;
/**
* 修改时间
*/
@ApiModelProperty(name = "modifyTime", value = "修改时间", hidden = true)
private Date modifyTime;
/**
* 性别 0男 1女 2 保密
*/
@ApiModelProperty(name = "sex", value = "0=女,1=男", dataType="int",example = "1")
@NotBlank(message = "{required}")
private String sex;
}
@ApiModel() 用于类 ;表示对类进行说明,用于参数用实体类接收
value–表示对象名
description–描述
都可省略
@ApiModelProperty() 用于方法,字段; 表示对model属性的说明或者数据操作更改
value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
hidden–隐藏