文章目录
前提
- 学过springboot
1.导包
<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.配置config类,访问ui页面
package cn.liuhao.config;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
// 开启swagger自动配置
@EnableSwagger2
public class SwaggerConfig {
}
配置这个类,通过springboot启动类启动后,访问http://localhost:8080/swagger-ui.html
访问成功则会出现以下页面表示成功
3.配置api文档信息
package cn.liuhao.config;
import java.util.ArrayList;
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.service.VendorExtension;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2 // 开启swagger
public class SwaggerConfig {
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}
/**
* api的基本信息
*
* @return
*/
public ApiInfo apiInfo() {
String title = "标题";
String description = "描述";
String version = "版本";
String termsOfServiceUrl = "所属组织公共网址";
String username = "创建者名称";
String userUrl = "创建者主页";
String userEmail = "创建者邮箱";
String licenseName = "许可证名称";
String licenseUrl = "许可证网络地址";
return new ApiInfo(title, description, version, termsOfServiceUrl, new Contact(username, userUrl, userEmail),
licenseName, licenseUrl, new ArrayList<VendorExtension>());
}
}
4.配置扫描指定路径的接口
4.1扫描指定包里的接口
swagger可以指定扫描项目包路径下的接口
修改swaggerConfig类
@Bean
public Docket docket() {
Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
// 在指定包路径下扫描接口
docket.select().apis(RequestHandlerSelectors.basePackage("cn.liuhao.controller")).build();
return docket;
}
4.2通过扫描指定注解获取接口
通过扫描指定类注解,获取所在类下的接口方法
@Bean
public Docket docket() {
Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
// 通过扫描指定注解,获取所在类下的接口方法
docket.select().apis(RequestHandlerSelectors.withClassAnnotation(RestController.class)).build();
return docket;
}
// 通过扫描指定方法注解,获取当前方法接口
@Bean
public Docket docket() {
Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
// 通过扫描指定方法注解,获取当前方法接口
docket.select().apis(RequestHandlerSelectors.withMethodAnnotation(RequestMapping.class)).build();
return docket;
}
4.3扫描所有接口,或者不扫描
扫描所有接口
@Bean
public Docket docket() {
Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
docket.select().apis(RequestHandlerSelectors.any()).build();
return docket;
}
不扫描任何接口
@Bean
public Docket docket() {
Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
docket.select().apis(RequestHandlerSelectors.none()).build();
return docket;
}
4.4 扫描指定包下的所有接口,并且使用过滤处指定类型接口外的其他接口
@Bean
public Docket docket() {
Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
// 扫描指定包下的所有接口,并且使用过滤处指定类型接口外的其他接口
docket.select().apis(RequestHandlerSelectors.basePackage("cn.liuhao.controller"))
.paths(PathSelectors.ant("/user")).build();
return docket;
}
5.配置接口忽略指定类型参数
例如忽略服务器自带的对象,request,response,session,application等
@Bean
public Docket docket() {
Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
// 忽略指定类型的接口参数
docket.ignoredParameterTypes(HttpServletRequest.class, HttpServletResponse.class);
return docket;
}
6.通过enable(bool)方法指定是否在展示页面
@Bean
public Docket docket() {
Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
// enable 方法接受一个boolean值,true代表展示页面,false代表不展示
docket.enable(true);
return docket;
}
不展示就会出现如下页面
7.为api配置分组
有多个分组就写多个bean实例
@Bean
public Docket docketUser() {
Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
docket.select().apis(RequestHandlerSelectors.basePackage("cn.liuhao.controller"))
.paths(PathSelectors.ant("/user/**")).build();
docket.groupName("用户接口");
return docket;
}
@Bean
public Docket docketHello() {
Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
docket.select().apis(RequestHandlerSelectors.basePackage("cn.liuhao.controller"))
.paths(PathSelectors.ant("/hello/**")).build();
docket.groupName("hello接口");
return docket;
}
8.配置实体信息
实体类
注解 | 作用 |
---|---|
@ApiModel | 用来描述一个类 |
@ApiModelProperty | 用来描述实体类的属性 |
package swagger03.web.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
@ApiModel("用户实体")
public class User {
@ApiModelProperty("ID")
private int id;
@ApiModelProperty("姓名")
private String name;
@ApiModelProperty("年龄")
private String age;
public int getId() {
return id;
}
public void setId(int id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getAge() {
return age;
}
public void setAge(String age) {
this.age = age;
}
public User(int id, String name, String age) {
super();
this.id = id;
this.name = name;
this.age = age;
}
public User() {
// TODO Auto-generated constructor stub
}
}
controller接口
注解 | 作用 |
---|---|
@RequestBody | 如果接口参数是一个实体类,虽然我们描述了实体类,但是作为接口参数,swagger并不会描述,我们需要手动添加 @RequestBody 来描述 |
package swagger03.web.controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import swagger03.web.pojo.User;
@RestController
@RequestMapping("user")
public class UserController {
// 注意,方法返回的类型一定要是我们描述好的实体类类型,否则swagger不能是被
// 返回user就必须用user类型当返回值,不能使用object
@GetMapping("getUser")
public User getUser(@RequestBody User u) {
return u;
}
}
9.配置全局参数(类似token这种参数)
代码
package swagger03.config;
import java.util.ArrayList;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
public Docket docket() {
Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(docketInfo());
// 在指定包路径下扫描接口
docket.select().apis(RequestHandlerSelectors.basePackage("swagger03.web.controller")).build();
// 创建全局参数类型可以是请求头参数(header),url参数(query)
Parameter token = new ParameterBuilder().name("token").description("用户令牌").parameterType("header")
.required(true).build();
// 添加参数
ArrayList<Parameter> paramers = new ArrayList<Parameter>();
paramers.add(token);
// 将参数集合放进docket对象
docket.globalOperationParameters(paramers);
return docket;
}
private ApiInfo docketInfo() {
return null;
}
}
10.接口以及参数配置
注解
注解名 | 含义 |
---|---|
@Api | 用来描述接口类的作用 |
@ApiOperation | 用来描述一个方法的作用 |
@ApiImplicitParams | 描述多个接口参数 |
@ApiImplicitParam | 描写单个接口参数的作用 |
package swagger03.web.controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import swagger03.web.pojo.User;
@Api(tags = "用户接口", description = "一些用户相关的参数")
@RestController
@RequestMapping("user")
public class UserController {
@ApiOperation("通过用户名和ID来获取用户对象")
@ApiImplicitParams({ @ApiImplicitParam(name = "id", dataType = "int", defaultValue = "0", required = true),
@ApiImplicitParam(name = "name", dataType = "String", defaultValue = "张三", required = true) })
@GetMapping
public User getUserById(int id, String name) {
return new User();
}
}
11.NumberFormatException异常解决办法
参考
推荐解决办法
<!--问题出现在1.5.20版本,1.5.22版本解决了这个问题,所以我们直接覆盖-->
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.5.22</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.5.22</version>
</dependency>