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