詳解io.springfox

io.springfox是一個開源的API文檔生成工具，它以Swagger為基礎，提供了更加豐富多樣的功能與配置選項。它的主要作用是生成可視化的API文檔，方便接口開發與調用者查閱API接口的相關信息，從而提高API的可理解性和易用性。

一、快速入門

使用io.springfox生成API文檔十分簡單，並且可以很方便地與Spring Boot項目進行整合。下面我們一步一步來看具體的操作。

首先我們需要在項目中引入依賴，如下所示：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

引入依賴後，我們需要在Spring Boot application類上添加@EnableSwagger2註解來啟用Swagger支持：

@EnableSwagger2
@SpringBootApplication
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

}

然後，在controller類的方法上加上@Api註解和@ApiOperation註解，其中@Api註解可以用於標識controller類，@ApiOperation註解則可以用於標識controller中具體的方法，示例代碼如下：

@RestController
@Api(tags = "示例接口")
public class SampleController {

    @ApiOperation("示例接口")
    @GetMapping("/sample")
    public String sample() {
        return "Hello World!";
    }
}

最後，在瀏覽器中輸入http://localhost:8080/swagger-ui.html，即可看到自動生成的API文檔頁面。

二、高級用法

除了基本用法以外，io.springfox還提供了很多高級功能，讓API文檔更加易用、易讀、易管理。

1.請求參數與響應參數的顯示與配置

在API文檔中，顯示請求參數與響應參數對於API使用者十分重要。可以使用各種註解來定義請求參數的數據類型、名稱、描述等信息。同時可以使用響應對象來定義響應參數的數據類型、名稱、描述等信息。

下面是一些常用的註解：

@RequestParam：用於標註請求參數，包含名稱、數據類型、是否必填、描述等信息。
@RequestBody：用於標註請求體，包含請求體的數據類型、描述等信息。
@ModelAttribute：用於標註JavaBean類型的請求參數，包含實體類的名稱、描述等信息。
@ApiImplicitParam：用於標註請求參數，包含名稱、數據類型、是否必填、描述等信息，可以與@RequestParam、@RequestBody等註解混合使用。
@ApiImplicitParams：用於標註多個請求參數，可以將@ApiImplicitParam註解集成在一起。
@ApiResponses：用於標註響應參數，包含響應的HTTP狀態碼、響應參數的數據類型、名稱、描述等信息。

示例代碼如下：

@RestController
@Api(tags = "樣例接口")
public class SampleController {

    @ApiOperation("獲取用戶信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用戶ID", dataType = "Long", paramType = "query", required = true),
            @ApiImplicitParam(name = "name", value = "用戶名", dataType = "String", paramType = "query", required = false)
    })
    @ApiResponses({
            @ApiResponse(code = 200, message = "成功", response = UserVO.class),
            @ApiResponse(code = 404, message = "用戶不存在")
    })
    @GetMapping("/user")
    public UserVO getUser(@RequestParam Long id, @RequestParam(required = false) String name) {
        return new UserVO(id, name);
    }
}

執行上述代碼後，可以在API文檔中看到請求參數和響應參數的詳細信息。

2.配置Swagger UI

Swagger UI是io.springfox中用於展示API文檔的組件，它提供了前端的交互界面和功能，包括請求測試、文檔注釋的查看等。Springfox允許自定義Swagger UI的界面和功能，以適應不同的需求。

比如，可以修改默認的Swagger UI主題，增加一些自定義的嵌入式文檔等功能。下面是一些常用的配置：

修改Swagger UI主題：可以使用springfox-swagger-ui的靜態資源文件進行自定義，比如將index.html文件複製到resources目錄下，並進行相關的修改。
增加自定義的文檔注釋：可以使用Swagger UI提供的“Markdown”語法來編寫文檔注釋，然後添加到Swagger配置中。
添加自定義的請求測試模型：可以在Swagger UI中添加自定義的請求測試模型，以便更好地測試API接口。

示例代碼如下：

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo())
                .useDefaultResponseMessages(false)
                .directModelSubstitute(LocalDateTime.class, String.class)
                .securitySchemes(Collections.singletonList(apiKey()))
                .securityContexts(Collections.singletonList(securityContext()))
                .globalOperationParameters(Collections.singletonList(parameter()))
                .ignoredParameterTypes(UserPassword.class)
                .forCodeGeneration(true)
                .directModelSubstitute(LocalDate.class, String.class)
                .genericModelSubstitutes(ResponseEntity.class)
                .protocols(newHashSet("http", "https"))
                .pathProvider(new RelativePathProvider(servletContext) {
                    {
                        this.leadingSlashIsOptional = false;
                        this.applicationPath = "/";
                    }
                })
                .tags(new Tag("樣例接口", "提供用戶信息查詢"));
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Springfox API文檔")
                .description("Springfox API文檔使用示例")
                .termsOfServiceUrl("http://springfox.io")
                .version("1.0.0")
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                .build();
    }

    private ApiKey apiKey() {
        return new ApiKey("mykey", "api_key", "header");
    }

    private SecurityContext securityContext() {
        return SecurityContext.builder()
                .securityReferences(
                        Collections.singletonList(new SecurityReference("mykey", new AuthorizationScope[]{new AuthorizationScope("global", "accessEverything")})))
                .forPaths(PathSelectors.any())
                .build();
    }

    private Parameter parameter() {
        return new ParameterBuilder()
                .name("Authorization")
                .description("認證令牌")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false)
                .build();
    }
}

上述代碼中，我們使用了Docket配置對象來創建Swagger文檔，並配合其他對象實現了多個高級功能。例如，我們可以看到使用了securitySchemes和securityContexts方法來定義了安全認證相關的配置信息，同時使用了globalOperationParameters方法定義了全局的請求參數等。

3.自定義錯誤信息

在API文檔中，錯誤信息的返回值通常是一個統一的格式，其中包括了錯誤的狀態碼、錯誤信息和錯誤的描述等。我們可以使用ExceptionHandler來統一處理異常，並返回自定義的錯誤信息。

下面是一個示例代碼：

@RestControllerAdvice
public class CustomExceptionHandler {

    @ExceptionHandler(Exception.class)
    public ResponseEntity<Result> handleException(Exception e) {
        log.error("系統錯誤：", e);
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(Result.fail("系統錯誤"));
    }

    @ExceptionHandler(NotFoundException.class)
    public ResponseEntity<Result> handleNotFoundException(NotFoundException e) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(Result.fail("數據不存在"));
    }
}

上述代碼中，我們使用了@RestControllerAdvice註解和ExceptionHandler註解來處理全局的異常和NotFoundException異常。在處理異常時，我們返回了自定義的錯誤信息，並且設置了相應的HTTP狀態碼。

三、結語

通過本篇文章我們可以了解到io.springfox在API文檔生成方面的強大，以及如何使用io.springfox快速創建API文檔，並優化API文檔的展示效果。同時我們也了解到了一些高級功能，例如如何自定義Swagger UI，自定義請求參數、響應參數和錯誤信息等。

最後，使用io.springfox生成API文檔是Java企業級開發中的重要工作，相比其他文檔生成工具，io.springfox具有更加豐富和強大、易用的特性，可以幫助Java開發者更加高效地處理API文檔相關的工作。

原創文章，作者：PLCL，如若轉載，請註明出處：https://www.506064.com/zh-hant/n/135157.html