Swagger is a powerful and easy-to-use API developer toolkit, suitable for teams and individuals, and can be developed throughout the API life cycle (from design and documentation to testing and deployment).
Swagger is made up of open source, free and commercially available tools. It enables anyone (from technical engineers to street smart product managers) to build amazing APIs that everyone likes.
Swagger is
built by SmartBear Software, which is the leader of the team's software quality tools. SmartBear lags behind some well-known companies in the software field, including Swagger, SoapUI and QAComplete.
One, Maven dependency
<!-- 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>
Two, register 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();
}
}
Three, 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;
}
Four, 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("错误");
}
}
}
After the configuration is complete, you can run it and you can generate API documentation, and it also supports online test interfaces. Type in the browser:
http://localhost:8081/swagger/swagger-ui.html
