Swagger | Swagger—REST APIs文档生成工具

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