关于springboot集成swagger及knife4j的增强问题

这篇攻略旨在帮助大家了解如何在Spring Boot项目中集成Swagger和Knife4j，并解决一些增强问题。

1. 引入依赖

首先，我们需要在pom.xml文件中引入Swagger和Knife4j的依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>版本号</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>版本号</version>
</dependency>

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-ui</artifactId>
    <version>版本号</version>
</dependency>

其中，springfox-swagger2是Swagger的核心依赖，springfox-swagger-ui提供Swagger的UI界面，knife4j-spring-ui则是Knife4j的UI界面。

2. 配置Swagger

在Spring Boot项目中，我们需要配置Swagger来启用它。在一个@Configuration类中，我们可以使用@EnableSwagger2注解来启用Swagger，同时也可以配置Swagger的一些属性，例如：

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API文档")
                .description("这是一个简单的示例")
                .contact(new Contact("作者", null, null))
                .version("1.0")
                .build();
    }
}

在上述代码中，我们首先创建了一个Docket实例。Docket实例可以用于配置Swagger的文档信息、接口信息等。我们使用apiInfo()方法设置文档信息（标题、描述、联系人、版本），使用select()方法配置哪些接口被扫描到，并应用RequestHandlerSelectors.basePackage()指定基础包。

3. 配置Knife4j

接下来，我们需要配置Knife4j。在SwaggerConfig类中，我们可以使用@Bean注解为Knife4j提供一个配置类：

@Configuration
public class Knife4jConfig {

    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("默认接口")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build()
                .enable(true);
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API文档")
                .description("这是一个简单的示例")
                .contact(new Contact("作者", null, null))
                .version("1.0")
                .build();
    }

}

在上述代码中，我们使用Docket创建了一个接口文档，并使用groupName()方法指定接口组名称，应用RequestHandlerSelectors.basePackage()指定接口扫描的基础包。

4. 在Controller中增加注解

最后，我们需要在Controller的接口方法上增加注解来让Swagger/Knife4j自动生成接口文档。例如，我们可以在Controller的接口方法上增加@ApiOperation、@ApiImplicitParam、@ApiImplicitParams等注解：

@RestController
@RequestMapping("/user")
@Api(tags = "用户管理")
public class UserController {

    @GetMapping("/{id}")
    @ApiOperation("获取用户信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "int", paramType = "path")
    public User getUser(@PathVariable("id") int id) {
        //...
    }

    @PostMapping("/")
    @ApiOperation("创建用户")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "user", value = "用户信息", required = true, dataType = "User")
    })
    public User addUser(@RequestBody User user) {
        //...
    }
}

在上述代码中，我们使用@ApiOperation注解为接口方法添加注释，使用@ApiImplicitParam、@ApiImplicitParams注解为接口方法的参数添加注释。

示例一

我们可以使用以下命令在项目中启动Swagger UI：

http://localhost:端口号/swagger-ui.html

在浏览器中使用以上网址，即可访问Swagger UI。

示例二

在项目中除了可以直接访问Swagger UI，也可以引入Knife4j UI，具体方法为在浏览器使用以下地址访问：

http://localhost:端口号/doc.html

以上访问地址将链接到Knife4j的API文档页面。

以上就是Spring Boot项目中集成Swagger和Knife4j的攻略，希望对您有所帮助。