Swagger是一套功能强大且易于使用的API开发人员工具套件,适用于团队和个人,可在整个API生命周期(从设计和文档到测试和部署)中进行开发。
Swagger由开放源代码,免费和市售工具共同组成,它使任何人(从技术工程师到街头智能产品经理)都可以构建每个人都喜欢的惊人API。
Swagger由SmartBear
Software构建,后者是团队软件质量工具的领导者。SmartBear落后于软件领域的一些知名公司,包括Swagger,SoapUI和QAComplete。
一、Maven依赖
<!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
二、注册Swagger(SwaggerConfig)
@Configuration
@EnableSwagger2
public class SwaggerConfig {
// 配置swagger2核心配置 docket
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2) // 指定api类型为swagger2
.groupName("jonsson") // 分组
.apiInfo(apiInfo()) // 用于定义api文档汇总信息
.select() // 通过.select()方法,去配置扫描接口。RequestHandlerSelectors配置如何扫描接口
/*
// RequestHandlerSelectors配置方法
any() // 扫描所有,项目中的所有接口都会被扫描到
none() // 不扫描接口
// 通过方法上的注解扫描,如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation( final Class<? extends Annotation> annotation)
// 通过类上的注解扫描,如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
withClassAnnotation( final Class<? extends Annotation> annotation)
basePackage( final String basePackage) // 根据包路径扫描接口
*/
.apis(RequestHandlerSelectors.basePackage("com.jonsson.controller")) // 指定controller包
/*
// 配置如何通过path过滤,即这里只扫描请求以/开头的接口
any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制
*/
.paths(PathSelectors.any()) // 所有controller
.build();
}
//构建 api文档的详细信息函数,注意这里的注解引用的是哪个
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot 使用 Swagger2 构建RESTful API") // 文档页标题
.contact(new Contact("jonsson", "https://blog.csdn.net/y1534414425", "[email protected]")) // 联系人信息
.version("1.0") // 文档版本号
.description("API 描述") // 描述
.build();
}
}
三、entity
@Data
@ApiModel("汽车")
public class Car {
@ApiModelProperty("主键")
private Integer id;
@ApiModelProperty("名称")
private String name;
@ApiModelProperty("价格")
private Integer price;
@ApiModelProperty("颜色")
private String colour;
@ApiModelProperty("品牌")
private String brand;
}
四、controller
@Api("汽车接口")
@RestController
@Slf4j
public class CarController {
@Autowired
private CarService carService;
@ApiOperation(value = "查询汽车列表")
@RequestMapping(value = "/carPage/{pageNum}/{pageSize}", method = RequestMethod.POST)
public ResultVO<Object> carPage(@ApiParam("当前页") @PathVariable("pageNum") Integer pageNum, @ApiParam("页大小") @PathVariable("pageSize") Integer pageSize) {
IPage<Car> carIPage = carService.findPage(pageNum, pageSize);
log.debug(carIPage.toString());
if (carIPage.getRecords().size() > 0) {
return ResultVOUtils.success(carIPage.getRecords());
} else {
return ResultVOUtils.error("错误");
}
}
}
配置结束后就可以运行是就可以生成API文档了,同时还支持在线测试接口。在浏览器中输入:
http://localhost:8081/swagger/swagger-ui.html