swagger与knife-4japi文档自动生成工具介绍

Swagger：API文档

Swagger 是一个用于设计、构建、文档化和测试API的强大工具。下面是一个示例，演示如何在Spring Boot应用程序中使用Swagger来定义和生成API文档：

首先，您需要添加Swagger的Maven依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

然后，创建一个Swagger配置类，以定义API规范并生成文档：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 替换为您的控制器包名
            .paths(PathSelectors.any())
            .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("Sample API Documentation")
            .description("API documentation for the Sample Application")
            .version("1.0")
            .build();
    }
}

在上述示例中，我们：

• 添加了Swagger的Maven依赖。
• 创建了一个名为SwaggerConfig的配置类，使用@EnableSwagger2注解启用Swagger。
• 配置了一个Docket bean，定义了API的基本信息，包括标题、描述和版本。
• 指定了要扫描的控制器包名。

接下来，您可以在控制器类中使用Swagger注解来描述API：

import org.springframework.web.bind.annotation.*;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;

@RestController
@RequestMapping("/api")
@Api(tags = "示例API")
public class SampleController {

    @GetMapping("/greet")
    @ApiOperation("获取问候语")
    public ResponseEntity<String> getGreeting(
        @ApiParam(value = "姓名", required = true) @RequestParam String name) {
        String greeting = "你好，" + name + "!";
        return ResponseEntity.ok(greeting);
    }
}

在这个示例中，我们使用了Swagger的注解：

• @Api：定义了API标签，用于组织和分类API。
• @ApiOperation：描述了API操作，包括操作名称和说明。
• @ApiParam：定义了操作的参数，包括参数名称、描述和是否必需。

现在，您可以启动应用程序并访问Swagger UI以查看和测试生成的API文档。Swagger UI通常位于以下URL：http://your-api-host:port/swagger-ui.html。

Knife4j：Swagger的增强版

Knife4j 是Swagger的增强版，提供了更美观、用户友好的界面，以及更灵活的配置选项。以下是如何集成Knife4j并定制Swagger文档的示例：

首先，添加Knife4j的Maven依赖：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.1</version>
</dependency>

然后，在Swagger配置类中进行定制，以启用Knife4j并设置文档属性：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 替换为您的

控制器包名
            .paths(PathSelectors.any())
            .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("Sample API Documentation")
            .description("API documentation for the Sample Application")
            .version("1.0")
            .build();
    }
}

与之前的Swagger配置类相似，但注意我们仍然使用Swagger的@EnableSwagger2注解。现在，我们需要添加Knife4j的一些自定义配置。

在application.properties或application.yml文件中，添加以下Knife4j配置属性，以启用Knife4j的特性：

knife4j:
  enable: true

现在，启动应用程序并访问Knife4j UI，它通常位于以下URL：http://your-api-host:port/doc.html。您将看到一个美观的Knife4j界面，允许您查看和测试API文档。

这篇博客文章介绍了Swagger和Knife4j，它们是API文档化和测试的强大工具。Swagger用于定义API规范并生成文档，而Knife4j则增强了Swagger的功能和界面，提供了更多的定制选项。通过合理使用这两个工具，您可以更轻松地管理和文档化您的API，使开发人员更容易理解和测试API。希望这篇文章对您有所帮助！