# easy-openapi

**Repository Path**: easy-framework/easy-openapi

## Basic Information

- **Project Name**: easy-openapi
- **Description**: 简化openapi的使用（可以搭配knife4j-openapi2-spring-boot-starter或knife4j-openapi3-spring-boot-starter一起使用）
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-24
- **Last Updated**: 2025-09-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## 介绍

简化openapi的使用（可以搭配knife4j-openapi2-spring-boot-starter或knife4j-openapi3-spring-boot-starter一起使用），当前基于jdk8和springboot2.X，点[此处](https://gitee.com/easy-framework/easy-springdoc)访问jdk21和springboot3.X的版本

## maven引用

```xml
<dependency>
    <groupId>io.github.xiaoyudeguang</groupId>
    <artifactId>easy-openapi</artifactId>
    <version>1.0.0</version>
</dependency>

<!--下面两个依赖任选其一-->
<!--openapi2-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>

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

## 在yml中添加配置

```yml
knife4j:
  enable: true
  openapi:
    title: Knife4j官方文档
    description: "`我是测试`,**你知道吗**
    # aaa"
    email: xiaoymin@foxmail.com
    concat: 八一菜刀
    url: https://docs.xiaominfo.com
    version: v4.0
    license: Apache 2.0
    license-url: https://stackoverflow.com/
    terms-of-service-url: https://stackoverflow.com/
    group:
      test1:
        group-name: 分组名称
        api-rule: package
        api-rule-resources:
          - com.example
```

## 接口添加文档注解

### 框架内置写法

```java
import com.example.model.SysUser;
import com.example.service.UserService;
import com.xiaoyudeguang.annotations.RequestMapping;
import com.xiaoyudeguang.annotations.RestController;
import io.swagger.v3.oas.annotations.Parameter;
import org.springframework.web.bind.annotation.RequestParam;

@RestController(value = "/user", tags = "用户接口", author = "赵光")
public class UserController {

    @Autowired
    private SysUserService sysUserService;

    @RequestMapping(value = "/getUserByUserNo", summary = "根据用户编码查询用户")
    public BaseResult<SysUser> getUserByUserNo(@RequestParam(value = "userNo") @Parameter(description = "用户编码") String userNo) {
        return BaseResult.ok(sysUserService.getOne(SysUser::getUserNo, userNo));
    }
}
```

### 原生写法

```java
import com.example.model.SysUser;
import com.example.service.UserService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@Tag(name = "用户接口")
@RestController
@RequestMapping(value = "/user")
public class UserController {

    @Autowired
    private SysUserService sysUserService;

    @Operation(summary = "根据用户编码查询用户")
    @RequestMapping(value = "/getUserByUserNo")
    public BaseResult<SysUser> getUserByUserNo(@RequestParam(value = "userNo") @Parameter(description = "用户编码") String userNo) {
        return BaseResult.ok(sysUserService.getOne(SysUser::getUserNo, userNo));
    }
}
```

### 访问链接：http://127.0.0.1:8080/doc.html