一、介绍Swagger2
Swagger是一款RESTful接口的文档在线自动生成、功能测试功能框架。一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务,加上swagger-ui,可以有很好的呈现。
二、常用注解
这里是说明常用注解的含义和基本用法(也就是说已经对swagger进行集成完成)
没有集成的请参见
SpringBoot集成springfox-swagger2构建restful API
SpringMVC集成springfox-swagger2构建restful API
官网WIKI
常用注解:
注解 | 作用处 | 描述 |
---|---|---|
@Api | 用于类 | 表示标识这个类是swagger的资源 |
@ApiOperation | 用于方法 | 表示一个http请求的操作 |
@ApiParam | 用于方法,参数,字段说明 | 表示对参数的添加元数据(说明或是否必填等) |
@ApiModel | 用于类 | 表示对类进行说明,用于参数用实体类接收 |
@ApiModelProperty | 用于方法,字段 | 表示对model属性的说明或者数据操作更改 |
@ApiIgnore | 用于类,方法,方法参数 | 表示这个方法或者类被忽略 |
@ApiImplicitParam | 用于方法 | 表示单独的请求参数 |
@ApiImplicitParams | 用于方法 | 包含多个 @ApiImplicitParam |
1、@Api()
用于类;表示标识这个类是swagger的资源
- tags–表示说明
- value–也是说明,可以使用tags替代
但是tags如果有多个值,会生成多个list
@Api(value="用户controller",tags={"用户操作接口"})
@RestController
public class UserController {
}
效果:
2、@ApiOperation()
用于方法;表示一个http请求的操作
- value用于方法描述
- notes用于提示内容
- tags可以重新分组(视情况而用)
3、@ApiParam()
用于方法,参数,字段说明;表示对参数的添加元数据(说明或是否必填等)
- name–参数名
- value–参数说明
- required–是否必填
@Api(value="用户controller",tags={"用户操作接口"})
@RestController
public class UserController {
@ApiOperation(value="获取用户信息",tags={"获取用户信息copy"},notes="注意问题点")
@GetMapping("/getUserInfo")
public User getUserInfo(@ApiParam(name="id",value="用户id",required=true) Long id,@ApiParam(name="username",value="用户名") String username) {
// userService可忽略,是业务逻辑
User user = userService.getUserInfo();
return user;
}
}
效果图:
4、@ApiModel()
用于类 ;表示对类进行说明,用于参数用实体类接收
- value–表示对象名
- description–描述
都可省略
5、@ApiModelProperty()
用于方法,字段; 表示对model属性的说明或者数据操作更改
- value–字段说明
- name–重写属性名字
- dataType–重写属性类型
- required–是否必填
- example–举例说明
- hidden–隐藏
entity bean类
@ApiModel(value="user对象",description="用户对象user") public class User implements Serializable{ private static final long serialVersionUID = 1L; @ApiModelProperty(value="用户名",name="username",example="xingguo") private String username; @ApiModelProperty(value="状态",name="state",required=true) private Integer state; private String password; private String nickName; private Integer isDeleted; @ApiModelProperty(value="id数组",hidden=true) private String[] ids; private List<String> idList; //省略get/set }
@ApiOperation("更改用户信息") @PostMapping("/updateUserInfo") public int updateUserInfo(@RequestBody @ApiParam(name="用户对象",value="传入json格式",required=true) User user){ int num = userService.updateUserInfo(user); return num; }
效果图:
6、@ApiIgnore()
用于类或者方法上,可以不被swagger显示在页面上
比较简单, 这里不做举例
7、@ApiImplicitParam()
用于方法
表示单独的请求参数
8、@ApiImplicitParams()
用于方法,包含多个 @ApiImplicitParam
- name–参数ming
- value–参数说明
- dataType–数据类型
- paramType–参数类型
- example–举例说明
@ApiOperation("查询测试")
@GetMapping("select")
//@ApiImplicitParam(name="name",value="用户名",dataType="String", paramType = "query")
@ApiImplicitParams({
@ApiImplicitParam(name="name",value="用户名",dataType="string", paramType = "query",example="xingguo"),
@ApiImplicitParam(name="id",value="用户id",dataType="long", paramType = "query")})
public void select(){
}
效果图:
三、springboot集成
1、添加maven依赖
<!--swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
<?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 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.marvin.demo</groupId>
<artifactId>SpringBoot_Swagger_learn_demo</artifactId>
<version>1.0-SNAPSHOT</version>
<packaging>jar</packaging>
<name>SpringBoot_Swagger_learn_demo</name>
<!--引用springBoot-->
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.1.4.RELEASE</version>
</parent>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
<java.version>1.8</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!--引入lombok-->
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>1.16.18</version>
</dependency>
<!--引入swagger2-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
</dependencies>
<build>
<plugins>
<!--配置boot运行插件-->
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
2、配置启动类
添加注解@EnableSwagger2
package com.marvin.demo;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@SpringBootApplication
@EnableSwagger2
public class SwaggerApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggerApplication.class);
}
}
3、编写配置文件(SwaggerConfig.java)
定义Docket的bean类
package com.marvin.demo.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;
@Configuration
public class SwaggerConfig {
/**
* 初始化创建Swagger Api
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)// 详细信息定制
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com"))//指定包路径,扫描com路径下的api文档
.paths(PathSelectors.any())//路径判断
.build();
}
/**
* 添加摘要信息(会在界面显示的信息)
*/
private ApiInfo apiInfo() {
// 用ApiInfoBuilder进行定制
return new ApiInfoBuilder()
.title("Swagger开发规范")//标题
.description("Saggger开发描述")
.termsOfServiceUrl("http://baidu.com")//(不可见)条款地址
.version("1.0.0")//版本号
.build();
}
}
4、controller 和 entity
5、结果测试
默认地址:http://localhost:8080/swagger-ui.html