springbootyml
Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTfu风格的web服务。目标是使客户端和文件系统作为服务器一同样的速度来更新文件的方法,参数和模型紧密集成到服务器。这个解释简单点来讲就是说,swagger是一款可以根据restful风格生成的接口开发文档,并且支持做测试的一款中间软件。
依赖坐标
Springfox Swagger UI
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
Springfox Swagger2
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
io.springfox</groupId>
springfox-swagger2</artifactId>
2.9.2</version>
</dependency>
io.springfox</groupId>
springfox-swagger-ui</artifactId>
2.9.2</version>
</dependency>
新建一个 SwaggerConfig 类
添加 @Configuration:表明这是一个配置类
开启 Swagger2
@Configuration //表明这是一个注解类
@EnableSwagger2 //开启 Swagger2
public class SwaggerConfig {
}
访问:http://localhost:8089/swagger-ui.html
package com.kuang.swagger.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;
import java.util.ArrayList;
/**
* @author Hedon Wang
* @create 2020-06-23 20:23
*/
@Configuration //表明这是一个注解类
@EnableSwagger2 //开启 Swagger2
public class SwaggerConfig {
/**
* 配置 Swagger 的 Docket 的 Bean 实例
* @return
*/
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
}
//配置 Swagger信息=apiInfo
private ApiInfo apiInfo(){
//作者信息
Contact contact = new Contact("Hedon","http://hedon.wang","[email protected]");
return new ApiInfo("Swagger API 文档", //文档标题
"这个是一个 Swagger 接口文档。", //文档描述
"v1.0", //文档版本
"http://heon.wang", //队伍的网站地址
contact, //作者信息
"Apache 2.0", //许可证
"http://www.apache.org/licenses/LICENSE-2.0",//许可证Url
new ArrayList());
}
}
在 SwaggerConfig 中对 Docket 对象继续进行设定
select().apis().paths().build()
/**
* 配置 Swagger 的 Docket 的 Bean 实例
* @return
*/
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo()) //配置 Swagger ApiInfo 基本信息
.select()
/**
* RequestHandlerSelectors配置要扫描接口的方式
* basePackage:指定要扫描的包=>RequestHandlerSelectors.basePackage("com.kuang.swagger.controller")
* any():扫描全部
* none():全部不扫描
* withClassAnnotation:扫描类上的注解=>RequestHandlerSelectors.withClassAnnotation(RestController.class)
* withMethodAnnotation:扫描方法上的注解=>RequestHandlerSelectors.withMethodAnnotation(GetMapping.class)
*/
.apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
/**
* Path:过滤路径
* ant:指定路径
* any:过滤全部
* none:全部不过滤
* regex:按照正则表达式来过滤
*/
.paths(PathSelectors.ant("/kuang/**"))
.build(); //工厂模式
}
重新访问:http://localhost:8089/swagger-ui.html
因为我们指定了映射路径为 /kuang/**,所以目前什么接口都没被扫描到
Docket.enable()
这里我们设置不启动
enable(false)
/**
* 配置 Swagger 的 Docket 的 Bean 实例
* @return
*/
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo()) //配置 Swagger ApiInfo 基本信息
.enable(false)
.select()
.apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
.paths(PathSelectors.ant("/kuang/**"))
.build(); //工厂模式
}
访问 http://localhost:8089/swagger-ui.html
Docket.groupName()
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo()) //配置 Swagger ApiInfo 基本信息
.groupName("Hedon")
.enable(true) //启动
.select()
.apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
.paths(PathSelectors.ant("/kuang/**"))
.build(); //工厂模式
}
访问: http://localhost:8089/swagger-ui.html
建立多个 Docket 实例对象
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("A");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("B");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("C");
}
访问: http://localhost:8089/swagger-ui.html
只要我们的接口中,返回值存在实体类,它就会被扫描到 Swagger 中
@PostMapping("/user")
public User user(){
return new User("heodn","12345");
}
访问: http://localhost:8089/swagger-ui.html
@ApiModel
@ApiModel("这是User实体类")
public class User {}
@ApiModelProperty
@ApiModelProperty("用户名")
public String username;
@ApiModelProperty("密码")
public String password;
@ApiOpeartion(value=“接口名”,httpMethod=“请求方式”,notes=“详细说明”)
@GetMapping("/hello")
@ApiOperation(value = "Hello接口",httpMethod = "GET",notes = "这是Hello接口的详细说明。")
public String hello(){
return "hello springboot";
}
@ApiImplicitParams 包含多个属性
@ApiImplicitParam
name:属性名
value:属性值
defaultValue:默认值
paramType:表示参数放在哪个地方
header–>请求参数的获取:@RequestHeader(代码中接收注解)
query–>请求参数的获取:@RequestParam(代码中接收注解)
path(用于restful接口)–>请求参数的获取:@PathVariable(代码中接收注解)
body–>请求参数的获取:@RequestBody(代码中接收注解)
form(不常用,form.serilize())
dataType:参数类型
required:是否必须
@GetMapping("/hello")
@ApiOperation(value = "Hello接口",httpMethod = "GET",notes = "这是Hello接口的详细说明。")
@ApiImplicitParams({
@ApiImplicitParam(name = "username",value = "用户名",defaultValue = "hedon",paramType = "query",dataType="String",required = true),
@ApiImplicitParam(name = "password",value = "密码",defaultValue = "hedonpassword",paramType = "query",dataType="String",required = true)
})
public String hello(String username,String password){
return "hello,your username = "+username +" and your password = "+password;
}
用在请求的类上,表示对类的说明,也代表了这个类是swagger2的资源。
参数:
tags:说明该类的作用,参数是个数组,可以填多个。
value=“该参数没什么意义,在UI界面上不显示,所以不用配置”
description = “用户基本信息操作”
用于方法,表示一个http请求访问该方法的操作。
参数:
value=“方法的用途和作用”
notes=“方法的注意事项和备注”
tags:说明该方法的作用,参数是个数组,可以填多个。
格式:tags={“作用1”,“作用2”}
(在这里建议不使用这个参数,会使界面看上去有点乱,前两个常用)
用于响应实体类上,用于说明实体作用。
参数:
description=“描述实体的作用”
用在属性上,描述实体类的属性
参数:
value=“用户名” 描述参数的意义
name=“name” 参数的变量名
required=true 参数是否必选
用在请求的方法上,包含多@ApiImplicitParam
用于方法,表示单独的请求参数。
参数:
name=“参数ming”
value=“参数说明”
dataType=“数据类型”
paramType=“query” 表示参数放在哪里
-header–>请求参数的获取:@RequestHeader(代码中接收注解)
-query–>请求参数的获取:@RequestParam(代码中接收注解)
-path(用于restful接口)–>请求参数的获取:@PathVariable(代码中接收注解)
-body–>请求参数的获取:@RequestBody(代码中接收注解)
-form(不常用,form.serilize())
defaultValue=“参数的默认值”
required=“true” 表示参数是否必须传
用于方法,参数,字段说明 表示对参数的要求和说明。
参数:
name=“参数名称”
value=“参数的简要说明”
defaultValue=“参数默认值”
required=“true” 表示属性是否必填,默认为false
用于请求的方法上,根据响应码表示不同响应。
一个@ApiResponses包含多个@ApiResponse。
用在请求的方法上,表示不同的响应。
参数:
code=“404” 表示响应码(int型),可自定义
message=“状态码对应的响应信息”
用于类或者方法上,不被显示在页面上。
用于配置类上,表示只对开发和测试环境有用。
package com.kuang.swagger;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@SpringBootApplication
@EnableSwagger2
public class SwaggerDemoApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggerDemoApplication.class, args);
}
}
package com.kuang.swagger.controller;
import com.kuang.swagger.pojo.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
/**
* @author Hedon Wang
* @create 2020-06-23 20:19
*/
@RestController
public class HelloController {
@GetMapping("/hello")
@ApiOperation(value = "Hello接口",httpMethod = "GET",notes = "这是Hello接口的详细说明。")
@ApiImplicitParams({
@ApiImplicitParam(name = "username",value = "用户名",defaultValue = "hedon",paramType = "query",dataType="String",required = true),
@ApiImplicitParam(name = "password",value = "密码",defaultValue = "hedonpassword",paramType = "query",dataType="String",required = true)
})
public String hello(String username,String password){
return "hello,your username = "+username +" and your password = "+password;
}
//只要我们的接口中,返回值存在实体类,它就会被扫描到 Swagger 中
@PostMapping("/user")
public User user(){
return new User("heodn","12345");
}
}
package com.kuang.swagger.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
/**
* @author Hedon Wang
* @create 2020-06-23 20:23
*/
@Configuration //表明这是一个注解类
@EnableSwagger2 //开启 Swagger2
public class SwaggerConfig {
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("A");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("B");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("C");
}
/**
* 配置 Swagger 的 Docket 的 Bean 实例
* @return
*/
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo()) //配置 Swagger ApiInfo 基本信息
.groupName("Hedon")
.enable(true) //启动
.select()
/**
* RequestHandlerSelectors配置要扫描接口的方式
* basePackage:指定要扫描的包=>RequestHandlerSelectors.basePackage("com.kuang.swagger.controller")
* any():扫描全部
* none():全部不扫描
* withClassAnnotation:扫描类上的注解=>RequestHandlerSelectors.withClassAnnotation(RestController.class)
* withMethodAnnotation:扫描方法上的注解=>RequestHandlerSelectors.withMethodAnnotation(GetMapping.class)
*/
.apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
/**
* Path:过滤路径
* ant:指定路径
* any:过滤全部
* none:全部不过滤
* regex:按照正则表达式来过滤
*/
.paths(PathSelectors.ant("/kuang/**"))
.build(); //工厂模式
}
//配置 Swagger信息=apiInfo
private ApiInfo apiInfo(){
//作者信息
Contact contact = new Contact("Hedon","http://hedon.wang","[email protected]");
return new ApiInfo("Swagger API 文档", //文档标题
"这个是一个 Swagger 接口文档。", //文档描述
"v1.0", //文档版本
"http://heon.wang", //队伍的网站地址
contact, //作者信息
"Apache 2.0", //许可证
"http://www.apache.org/licenses/LICENSE-2.0",//许可证Url
new ArrayList());
}
}
package com.kuang.swagger.pojo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
/**
* @author Hedon Wang
* @create 2020-06-23 21:27
*/
@ApiModel("这是User实体类")
public class User {
@ApiModelProperty("用户名")
public String username;
@ApiModelProperty("密码")
public 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;
}
public User() {
}
public User(String username, String password) {
this.username = username;
this.password = password;
}
@Override
public String toString() {
return "User{" +
"username='" + username + '\'' +
", password='" + password + '\'' +
'}';
}
}