详解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/n/135157.html