1、导入SwaggerJar包(最新版2.9.2)
<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、编写SwaggerConfig配置:
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo()).select().build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("学习Swagger")
.description("API接口说明文档")
.version("1.0-Beta")
.termsOfServiceUrl("https://www.码农老中医.com")
.contact(new Contact("码农老中医", "https://www.码农老中医.com", null))
.license("https://www.码农老中医.com")
.licenseUrl("https://www.码农老中医.com")
.build();
}
}
- 创建一个Maven项目导入Swagger相关的Jar包,启动项目浏览器地址输入http://localhost:8080/swagger-ui.html如图所示:
简单的Swagger就配置完成了,在apiInfo()这个方法里面,参数很多,其实没有必须要配置完全,把重要的信息配置上即可,在这个只是一个案例。
- 使用RequestHandlerSelectors方法来设置Swagger扫描接口:
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any()).build()
;
}
}
RequestHandlerSelectors方法中有5个参数:
any:默认扫描所有接口
none:不扫描
basePackage:按照包扫描
withClassAnnotation:扫描类上的注解
withMethodAnnotation:扫描方法上的注解
- 使用PathSelectors方法过滤接口:
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.xx.swagger.controller"))
// 只需要hello下面的所有请求。
.paths(PathSelectors.ant("/hello/**"))
.build()
;
}
}
PathSelectors方法中有4个参数:
ant:通过表达式
any:默认扫描所有接口
none:不扫描
regex:用正则表达式来判断,true = 扫描 / false 不扫描
- 使用ignoredParameterTypes配置接口忽略参数:
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
// 接口中所有Integer类型的参数,全部忽略。
.ignoredParameterTypes(Integer.class)
;
}
}
- 在不同的环境下配置是否启动Swagger:
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Autowired
Environment environment;
@Bean
public Docket createRestApi() {
Profiles profiles = Profiles.of("dev", "test");
boolean isEnable = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.enable(isEnable)
;
}
}
enable()方法返回一个boolean类型的值,默认为true,false时不可访问。
在resources新建4个配置文件为:
application.yml:
spring:
profiles:
active: prod
application-dev.yml:开发环境
application-prod.yml:生产环境
application-test.yml:测试环境
- API接口分组:
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket docketUser() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("用户")
.select().paths(PathSelectors.ant("/user")).build();
}
@Bean
public Docket docketHello() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("你好")
.select().paths(PathSelectors.ant("/hello")).build();
}
}
- 展示实体类:
@ApiOperation("添加用户信息")
@PostMapping
public User insertUser(User users) {
return users;
}
@Data
@AllArgsConstructor
@ApiModel("用户实体类")
public class User implements Serializable {
@ApiModelProperty("用户名")
private String username;
@ApiModelProperty("年龄")
private Integer age;
}
@ApiModelProperty(value = "参数说明", name = "参数", required = 是否必传,example="示例")
- 配置全局参数:
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket docket() {
Parameter token = new ParameterBuilder().name("token")
.description("用户登录令牌")
.parameterType("header")
.modelRef(new ModelRef("String"))
.required(true)
.build();
List<Parameter> parameter = new ArrayList<>();
parameter.add(token);
return new Docket(DocumentationType.SWAGGER_2)
.globalOperationParameters(parameter);
}
}
- 使用@Api注解和@ApiOperation注解说明:
@Api(tags = "用户信息")
@RestController
@RequestMapping("/user")
public class UserController {
@ApiOperation("获取用户信息")
@GetMapping
public String getUser() {
return "users";
}
}
@Api:在类上使用
@ApiOperation:在方法上使用
- 使用@ApiImplicitParams或@ApiImplicitParam配置接口参数说明:
@Api(tags = "用户信息")
@RestController
@RequestMapping("/user")
public class UserController {
@ApiOperation("获取用户信息")
@ApiImplicitParams(
{
@ApiImplicitParam(name = "username", value = "用户名",defaultValue = "张三",example = "lisi",required = true),
@ApiImplicitParam(name = "username", value = "密码", required = true)
}
)
@GetMapping
public String getUser(String username, String password) {
return "users";
}
}
在查看接口时 defaultValue 的值会显示出来
点击 Try it out 以后 example 的值才会显示
- 多个参数写法:
@ApiImplicitParams({
@ApiImplicitParam(参数1),
@ApiImplicitParam(参数1),
@ApiImplicitParam(参数1)
})
如果真的是接收多个参数,最好用实体类去接收。
- 一个参数写法:
@ApiImplicitParam(参数)
- 解决java.lang.NumberFormatException: For input string: ""错误:
- 第一种解决方法:
在实体类中用@ApiModelProperty注解时加上example
- 第二种解决方法:
Jar包版本:
<swagger2.version>2.9.2</swagger2.version>
<swagger.version>1.5.22</swagger.version>
步骤一:先把swagger2中的annotations和models排除掉
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger2.version}</version>
<exclusions>
<exclusion>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
</exclusion>
<exclusion>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger2.version}</version>
</dependency>
步骤二:自己引入annotations和models Jar包信息
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
<version>${swagger.version}</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>${swagger.version}</version>
</dependency>
注:有可能只需要排除models即可。
这个是没有排除时报错的地方。
引入1.5.22版本的,再去查看之前报错的地方。