Swagger-Bootstrap-UI（Knife4j）使用教程

Swagger-Bootstrap-UI（Knife4j）使用教程

swagger-bootstrap-ui Knife4j is a set of Swagger2 and OpenAPI3 All-in-one enhancement solution 项目地址: https://gitcode.com/gh_mirrors/sw/swagger-bootstrap-ui

1. 项目介绍

Swagger-Bootstrap-UI 是一套基于 Swagger2 和 OpenAPI3 的增强解决方案，已更名为 Knife4j。它不仅提供了 UI 展示层的增强，还增加了更多个性化的特性增强功能。 Knife4j 依赖于 Spring MVC、Spring Boot、Spring Cloud 等框架，主要支持 Java 开发，同时提供了离线版本，适用于任何语言中使用 Swagger 的场景。

2. 项目快速启动

2.1 添加 Maven 依赖

首先，在项目的 pom.xml 文件中添加以下 Maven 依赖：

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

2.2 创建 Config 配置类

接着，在项目中创建一个配置类 SwaggerConfig：

@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfig {

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

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("标题：springboot整合Knife4j项目API文档")
                .description("描述：springboot整合Knife4j项目API文档")
                .termsOfServiceUrl("https://www.cnblogs.com/tanghaorong")
                .contact(new Contact("唐浩荣", "www.tanghaorong.com", "XXXXXX@qq.com"))
                .license("Apache 3.0")
                .version("v1.0")
                .build();
    }
}

2.3 编写 Restful 接口

在 com.thr.controller 包下创建 UserController 控制器类：

@Api(value = "用户", tags = "用户信息模块")
@RestController
@RequestMapping(value = "/user")
public class UserController {

    @Autowired
    private UserService userService;

    @GetMapping(value = "/findAll")
    @ApiOperation(value = "查询所有用户信息", notes = "获取所有用户信息")
    public List<User> findAll() {
        List<User> userList = userService.findAll();
        return userList;
    }

    @GetMapping(value = "/findUserById/{id}")
    @ApiOperation(value = "根据id查询用户信息", notes = "根据id获取用户信息")
    public User findUserById(@PathVariable(value = "id") Integer id) {
        return userService.findUserById(id);
    }

    @PostMapping(value = "/addUser")
    @ApiOperation(value = "添加用户信息")
    public void addUser(User user) {
        user.setUsername("John");
        user.setPassword("123456");
        user.setAge(22);
        user.setAddress("中国重庆");
        userService.addUser(user);
    }

    @PutMapping(value = "/updateUserById")
    @ApiOperation(value = "修改用户信息")
    public void updateUserById(User user) {
        user.setId(3L);
        user.setUsername("Marry");
        user.setPassword("123456");
        user.setAge(20);
        user.setAddress("中国湖南");
        userService.updateUserById(user);
    }

    @DeleteMapping(value = "/deleteUserById/{id}")
    @ApiOperation(value = "删除用户信息")
    public void deleteUserById(@PathVariable(value = "id") Integer id) {
        System.out.println("Delete请求");
        userService.deleteUserById(id);
    }
}

2.4 启动项目

启动 Spring Boot 项目，如果没有报错，访问以下地址查看 API 文档：

http://localhost:[自己设置的端口]/doc.html

例如，若端口设置为 8080，则访问 http://localhost:8080/doc.html。

3. 应用案例和最佳实践

• 集成 Knife4j 到 Spring Boot 项目：可以参考上面的快速启动部分，按照步骤集成并配置。
• 接口文档维护：利用 Knife4j 的注解，可以对接口进行详细的描述，有助于文档的维护和生成。
• 接口调试：Knife4j 提供了类似 PostMan 的接口调试功能，方便开发者测试接口。

4. 典型生态项目

• Knife4j-Desktop：一个独立的桌面版 Swagger UI，方便在没有网络的情况下使用。
• Knife4j-Doc：Knife4j 的文档项目，包含了详细的 Knife4j 使用说明和文档。

swagger-bootstrap-ui Knife4j is a set of Swagger2 and OpenAPI3 All-in-one enhancement solution 项目地址: https://gitcode.com/gh_mirrors/sw/swagger-bootstrap-ui