一、导包
<!--引入swagger-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!--前端的UI界面-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
二、编写配置类
import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.swaggerdemo"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 标题
.title("Spring Boot中使用Swagger2构建RESTful APIs 的标题")
// Swagger文档的版本号
.version("1.0")
// 标题的详细描述
.description("Spring Boot中使用Swagger2构建RESTful APIs 的详细描述")
// 友链,用的少
.termsOfServiceUrl("http://www.baidu.com")
// 联系人信息
.contact(new Contact("蒋劲豪",
"http://www.hao123.com",
"718009739@qq.com"
))
// 协议,自定义的
.license("Apache 2.0")
// 把协议变成超链接
.licenseUrl("http://www.bilibili.com")
.build();
}
}
三、接口文档的访问地址
http://localhost:8080/swagger-ui.html
四、常见问题
SpringBoot和Swagger有版本不兼容问题,如果版本不兼容会出现以下异常:
解决办法:
(一)换兼容的版本
(二)改配置文件
spring:
mvc:
pathmatch:
matching-strategy: ant_path_matcher
五、Controller类的案例
import com.example.swaggerdemo.entity.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/userController")
@Api(tags = {"用户接口"})
public class UserController {
@ApiOperation(value = "新增用户接口", notes = "新增用户接口的详细描述")
// 对请求参数进行说明
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户编号", dataType = "string",
paramType = "query", required = true, defaultValue = "1001"),
// 如果参数在请求头中 paramType = "header"
// 如果参数在路径中 paramType = "path"
// 如果参数在请求体中 paramType = "query"
@ApiImplicitParam(name = "name", value = "用户姓名", dataType = "string",
paramType = "query", required = true, defaultValue = "tom")
})
// 对响应结果进行说明
@ApiResponses({
@ApiResponse(code = 200, message = "success", response = User.class)
})
@PostMapping("/addUser")
public String addUser(User user) {
return "新增用户成功!";
}
}
六、实体类的案例
package com.example.swaggerdemo.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "User", description = "用户的实体类")
public class User {
@ApiModelProperty(value = "用户编号")
private String id;
@ApiModelProperty(value = "用户姓名")
private String name;
}
七、换其他的前端UI
如果不喜欢默认的UI界面,可以换一个前端UI界面;
(一)导包
<!--新UI-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
(二)添加注解
在SwaggerConfig配置类上加上注解
@EnableSwaggerBootstrapUI
(三)接口文档的访问地址
http://localhost:8080/doc.html