SpringBoot整合knife4j3.0.3实现过程
<div id="navCategory"><h5 class="catalogue">目录</h5><ul class="first_class_ul"><li>配置</li><li>Swagger使用</li><ul class="second_class_ul"><li>使用</li></ul><li>接口字段说明</li><ul class="second_class_ul"></ul><li>Knife4j 增强功能</li><ul class="second_class_ul"></ul><li>总结</li><ul class="second_class_ul"></ul></ul></div><p>在Spring Boot项目中，我们可以通过引入Swagger依赖，然后在Controller中加入相应注解，即可生成API文档。Swagger提供了一个Web界面，在这个界面上可以查看所有API的信息，包括请求方法、参数、响应码等。</p><p>Knife4j是Swagger-UI的增强版，它是在Swagger-UI的基础上进行了改进和优化，提供了更加完善的交互体验和更加美观的UI设计。同时，它也提供了更多的扩展功能，例如在线调试和多语言支持等。</p>
<p class="maodian"></p><h2>配置</h2>
<p>pom.xml:</p>
<div class="jb51code"><pre class="brush:xml;"> <dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.3</version>
</dependency>
</pre></div>
<p class="maodian"></p><h2>Swagger使用</h2>
<p>在Spring Boot项目中，Controller通常会有多个接口，我们可以通过在Controller类上添加@Api注解来为API接口添加描述信息，以及使用@ApiOperation注解来为单个接口添加描述信息。</p>
<p class="maodian"></p><h3>使用</h3>
<p>在Spring Boot项目中，我们可以通过Swagger注解@Api来定义接口分组。@Api注解指定了该Controller的标签为“用户管理”，这个标签将作为接口分组的名称：：</p>
<div class="jb51code"><pre class="brush:java;">@RestController
@RequestMapping("/users")
@Api(tags = "用户管理")
public class UserApi {
}
</pre></div>
<p>当一个Controller包含多个接口时，可以通过@ApiOperation注解指定每个接口的简介和说明。例如：</p>
<div class="jb51code"><pre class="brush:java;">@RestController
@RequestMapping("/users")
@Api(tags = "用户管理")
public class UserApi {
@GetMapping("/{id}")
@ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户信息")
public User getUserById(@PathVariable("id") Long id) {
}
@PostMapping
@ApiOperation(value = "创建用户", notes = "创建新用户")
public User createUser(@RequestBody User user) {
}
// ...
}
</pre></div>
<p>此外，设置项目的基本信息也是有必要的。</p>
<div class="jb51code"><pre class="brush:java;">@EnableOpenApi
@Configuration
public class DocumentConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.jp"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("管理平台API文档")
.description("管理系统")
.contact(new Contact("jp", "", ""))
.version("2.0.0")
.build();
}
}
</pre></div>
<p>打开API文档地址：</p>
<p style="text-align:center"><img alt="" src="https://img.jbzj.com/file_images/article/202601/2026010814314554.png" /></p>
<p class="maodian"></p><h2>接口字段说明</h2>
<p>Swagger提供了@ApiImplicitParam注解。</p>
<p>下面演示使用@ApiImplicitParam注解指定了每个参数的名称、类型和说明：</p>
<div class="jb51code"><pre class="brush:java;">@RestController
@RequestMapping("/users")
@Api(tags = "用户管理")
public class UserApi {
@GetMapping("/{id}")
@ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户信息")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path")
public User getUserById(@PathVariable("id") Long id) {
// ...
}
@PostMapping
@ApiOperation(value = "创建用户", notes = "创建新用户")
@ApiImplicitParams({
@ApiImplicitParam(name = "user", value = "用户实体", required = true, dataType = "User", paramType = "body")
})
public User createUser(@RequestBody User user) {
// ...
}
// ...
}
</pre></div>
<p style="text-align:center"><img alt="" src="https://img.jbzj.com/file_images/article/202601/2026010814314593.png" /></p>
<p class="maodian"></p><h2>Knife4j 增强功能</h2>
<ul><li><strong>离线文档导出：</strong> 用户可以直接在界面上导出 HTML、Markdown 或 Word 格式的离线文档，这对于没有网络环境下的开发、分享或者存档非常有用。</li><li><strong>接口排序与分组：</strong> Knife4j 支持对API接口进行自定义排序和分组，使得文档结构更加清晰有序，方便用户快速定位到所需接口。</li><li><strong>在线调试与数据模拟：</strong> 除了基本的接口调用测试外，Knife4j 还增强了在线调试功能，支持设置请求头、Cookie、Body等多种参数，以及保存历史请求、导入导出测试数据等，便于开发者快速验证API功能。</li><li><strong>登录认证支持：</strong> 为了保护API文档的安全，Knife4j 支持多种登录认证方式（如Basic Auth、OAuth2等），可以对接企业的统一认证系统，确保只有授权用户才能访问API文档。</li><li><strong>国际化支持：</strong> 内置多语言支持，可以根据用户浏览器的语言偏好自动切换界面语言，提高国际团队的协作效率。</li></ul>
<p class="maodian"></p><h2>总结</h2>
<p>Spring Boot与Knife4j 3.0.3的整合，是提升API管理水平和团队协作效率的有效手段。</p>
<p>它不仅简化了API文档的创建和维护工作，还通过增强的功能特性，为开发者和API使用者带来了前所未有的便利。</p>
<p>无论是对于快速发展的创业公司还是大型企业级项目，这种整合都是构建高质量API不可或缺的一部分。</p>
<p>以上为个人经验，希望能给大家一个参考，也希望大家多多支持琼殿技术社区。</p>
<div class="art_xg">
<b>您可能感兴趣的文章:</b><ul><li>springboot3整合knife4j超详细教程(不带swagger2玩)</li><li>SpringBoot整合Knife4j的实战示例</li><li>SpringBoot3.x整合Knife4j接口文档</li><li>SpringBoot整合knife4j实践</li><li>SpringBoot与knife4j的整合使用过程</li><li>springboot3整合knife4j详细图文教程(swagger增强)</li></ul>
</div>
</div>
<!--endmain-->
頁:
[1]