首页 > 其他分享 >接口文档[Knife4j]

接口文档[Knife4j]

时间:2024-11-05 21:21:34浏览次数:3  
标签:Knife4j description 接口 id 文档 com public

接口文档[Knife4j]

接口文档是描述 API 接口的详细文档,通常用于沟通开发、测试和使用 API 的团队。一个好的接口文档不仅能够让开发人员明确接口的使用方法,还可以帮助使用者理解 API 的功能和预期行为。

Knife4j 使用,参考:https://doc.xiaominfo.com/docs/quick-start

swagger标准常用注解;

访问 http://ip:port/doc.html 即可查看接口文档

访问 http://ip:port/doc.html 即可查看接口文档

注解 标注位置 作用
@Tag controller 类 描述 controller 作用
@Parameter 参数 标识参数作用
@Parameters 参数 参数多重说明
@Schema model 层的 JavaBean 描述模型作用及每个属性
@Operation 方法 描述方法作用
@ApiResponse 方法 描述响应状态码等

方法一

添加依赖

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

创建application.yaml文件

# springdoc-openapi项目配置      
springdoc:
  api-docs:
    path: /api-docs  # 配置 OpenAPI 文档的路径
  swagger-ui:
    path: /swagger-ui.html  # 配置 Swagger UI 的路径
    enabled: true  # 启用 Swagger UI
    
  # 定制文档基本信息
  info:
    title: API 文档标题  # 设置文档标题
    description: API 文档描述  # 设置文档描述
    version: 1.0.0  # 设置 API 版本
    terms-of-service: https://example.com/terms  # 服务条款 URL
    
    # 关于开发者
    contact:
      name: 开发者姓名  # 开发者联系人姓名
      url: https://example.com/contact  # 联系方式 URL
      email: [email protected]  # 开发者联系邮箱
      
    # 关于许可证
    license:
      name: Apache 2.0  # 许可证名称
      url: https://www.apache.org/licenses/LICENSE-2.0.html  # 许可证 URL
      
  # 定制服务器基本信息
  servers:
    - url: http://localhost:8080  # 服务器 URL
      description: 本地服务器  # 服务器描述
    - url: https://api.example.com  # 服务器 URL
      description: 生产服务器  # 服务器描述
      
  # 定制外部文档信息
  external-docs:
    description: 外部文档描述  # 外部文档描述
    url: https://example.com/docs  # 外部文档 URL
    
   #这里定义了两个分组,可定义多个,也可以不定义
  group-configs:
      #分组名
    - group: admin
      #按路径匹配
      pathsToMatch: /admin/**
      #分组名
    - group: user
      #按包路径匹配
      packagesToScan: com.hello.api.user
      
     
# knife4j的增强配置,不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn

使用OpenAPI3的规范注解,注释各个Spring的REST接口

@RestController
@Tag(name = "名")  //本controller类的介绍
public class BodyController {
    
   @Operation(summary = "普通body请求") //方法的介绍
   @PostMapping("/body")
   public ResponseEntity<> body(@RequestBody FileResp fileResp){
       return ResponseEntity.ok();
   }
    
  @Parameters({
       @Parameter(name = "id", description = "员工id", in = ParameterIn.PATH,required = true) //参数的介绍
    })
    @Operation(summary="按照id查询员工信息")
    @GetMapping("/employee/{id}")
    public R get(@PathVariable("id") Long id){
        //进行脱敏以后返回给前端
        return R.ok(respVo);
    }
}
@Schema(description = "员工修改提交的数据")  //属性的描述
@Data
public class EmployeeUpdateVo {
    @Schema(description = "员工id")
    private Long id;
}

方法二

引入Maven 依赖

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

创建配置类

@Configuration
public class Knife4jConfiguration {
    //设置doc.html首先
    @Bean
    public OpenAPI openAPI() {
        Contact contact = new Contact();
        contact.setName("名字");
        return new OpenAPI()
                .info(new Info()
                        .title("hello-knife4j项目API")
                        .contact(contact)
                        .version("1.0")
                        .description("hello-knife4j项目的接口文档"));
    }
    
   //指定接口文档的分组
    @Bean
    public GroupedOpenApi userAPI(){
        return GroupedOpenApi.builder()
                .group("user")
                .displayName("用户接口")
                .pathsToMatch("/user/**").build();
    }

    @Bean
    public GroupedOpenApi loginAPI(){
        return GroupedOpenApi.builder()
                .group("login")
                .displayName("登录接口")
                .pathsToMatch("/login/**").build();
    }
}

启动项目

启动SpringBoot项目,访问http://localhost:8080/doc.html,观察接口文档。

标签:Knife4j,description,接口,id,文档,com,public
From: https://www.cnblogs.com/21CHS/p/18528878

相关文章

  • CompletableFuture异步编排接口优化方案
    接口优化方案(1)程序本身,减少不必要的条件判断、循环(2)减少数据库的交互次数,以及每个sql查询的数据量(列数和行数越少越好)(3)提高sql的性能,通过建立合适的索引(4)使用java8的stream流提高集合的遍历操作的效率(5)引入缓存,从redis中加载数据的效率高于mysql(6)使用多线程异步......
  • \\:ip 访问网络上的SMB共享目录、IP接口传输数据、ftp://ip ftp传输
    一、访问网络上的SMB共享目录1.导入JAR包 <!--访问网络上的SMB共享目录--> <dependency> <groupId>com.hierynomus</groupId> <artifactId>smbj</artifactId> <version>0.13.0</version> </dependency>2.使用//定义......
  • 基于SpringBoot+Vue的库存管理系统设计与实现毕设(文档+源码)
            目录一、项目介绍二、开发环境三、功能介绍四、核心代码五、效果图六、源码获取:        大家好呀,我是一个混迹在java圈的码农。今天要和大家分享的是一款基于SpringBoot+Vue的库存试管理系统,项目源码请点击文章末尾联系我哦~目前有各类成品......
  • 基于SpringBoot+Vue的疗养院管理系统设计与实现毕设(文档+源码)
            目录一、项目介绍二、开发环境三、功能介绍四、核心代码五、效果图六、源码获取:        大家好呀,我是一个混迹在java圈的码农。今天要和大家分享的是一款基于SpringBoot+Vue的疗养院管理系统,项目源码请点击文章末尾联系我哦~目前有各类成品......
  • 【Azure App Service】使用Microsoft.Office.Interop.Word来操作Word文档,部署到App Se
    问题描述在.NET项目中,使用Microsoft.Office.Interop.Word组件来操作Word文档,使用了Microsoft.Office.Interop.Word.Document对象中的Open和SaveAs方法。##打开文件doc=app.Documents.Open(refinputFile,refnullobj,refnullobj,refnullobj,refnullobj,refnullobj,......
  • 2024/11/5日 日志 关于BOM浏览器对象模型和DOM文档对象模型的学习与笔记整理
    和Javascript有关的BOM与DOM及事件监听。以下是今天的内容点击查看代码--BOM--BrowserObjectModel浏览器对象模型--JavaScript将浏览器的各个组成部分封装为对象--组成:--Window:浏览器窗口对象--Navigator:浏览器对象--Screen:屏幕对象--History:历史记录......
  • 举例说明什么情况下会更倾向于使用抽象类而不是接口
    接口和抽象类都遵循”面向接口而不是实现编码”设计原则,它可以增加代码的灵活性,可以适应不断变化的需求。接口vs抽象类 继承限制:Java中,一个类只能继承一个类,但可以实现多个接口。继承一个类意味着失去了继承其他类的机会。行为表示:接口通常用于表示附加的行为......
  • 举例说明什么情况下会更倾向于使用抽象类而不是接口
    接口和抽象类都遵循”面向接口而不是实现编码”设计原则,它可以增加代码的灵活性,可以适应不断变化的需求。接口vs抽象类 继承限制:Java中,一个类只能继承一个类,但可以实现多个接口。继承一个类意味着失去了继承其他类的机会。行为表示:接口通常用于表示附加的行为......
  • 实时金融股票数据API接口websocket接入方法
    一、使用websocket的协议提升传输速度实时金融股票数据对于投资者和交易员来说至关重要。通过使用WebSocket接入方法,可以轻松获取实时金融股票类数据并及时做出决策。WebSocket是一种高效的双向通信协议,它允许数据的实时推送,避免了不断的轮询请求。这种接入方法具有多个优势。......
  • 后端整合 Swagger + Knife4j 接口文档
    什么是接口文档?写接口信息的文档,每条接口包括:请求参数响应参数错误码接口地址接口名称请求类型请求格式备注who谁用?一般是后端或者负责人来提供,后端和前端都要使用为什么需要接口文档?有个书面内容(背书或者归档),便于大家参考和查阅,便于沉淀和维护,拒绝口口相......