# iuyy-api-doc

**Repository Path**: iuyy_net/iuyy-api-doc

## Basic Information

- **Project Name**: iuyy-api-doc
- **Description**: 用来生成 API 文档及 API 测试，简单易用，无代码侵入。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: https://gitee.com/iuyy_net/iuyy-api-doc
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2020-05-12
- **Last Updated**: 2021-03-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# iuyy-api-doc

### 介绍
其于Spring框架，项目会自动扫描 controller 的注解，生成 API 文档。

增加了 API 测试功能。

简单易用。



### 软件架构
基于Spring框架。



### 使用说明

##### 1、添加依赖

```xml
<dependency>
    <groupId>net.iuyy</groupId>
    <artifactId>iuyy-api-doc</artifactId>
    <version>1.5</version>
</dependency>
```



##### 2、添加配置文件

```java
@Configuration
@ApiDoc(basePackages = "net.iuyy.demo.controller")
public class ApiDocConfig {
    @Bean
    public ServletRegistrationBean apiDocServlet() {
        ServletRegistrationBean registrationBean = new ServletRegistrationBean(new ApiDocServlet(), "/api/doc/*");
        registrationBean.setLoadOnStartup(1);
        return registrationBean;
     }
}

```

##### 3、添加注解（非必需）

> 注：如果想在接口文档页面看到更详细的返回值结构，请添加此注解。

示例：

```java
@RestController
@RequestMapping("blog")
public class BlogApi {

    @Autowired
    private BlogService blogService;

    @GetMapping()
    @ReturnType(value = "java.util.List<net.iuyy.demo.bean.Blog>")
    public JsonResult getAll(){
        return new JsonResult(blogService.getAll());
    }

    @GetMapping("/{id}")
    @ReturnType(value = "net.iuyy.demo.bean.Blog")
    public JsonResult getOneById(@PathVariable("id") Integer id){
        return new JsonResult(blogService.getOneById(id));
    }

    @PostMapping()
    public JsonResult update(@RequestBody Blog blog){
        return blogService.update(blog) ? JsonResult.SUCCESS : JsonResult.FAILED;
    }

    @PutMapping()
    public JsonResult add(@RequestBody Blog blog){
        return blogService.add(blog) ? JsonResult.SUCCESS : JsonResult.FAILED;
    }

    @DeleteMapping("/{id}")
    public JsonResult delete(@PathVariable("id") Integer id){
        return blogService.delete(id) ? JsonResult.SUCCESS : JsonResult.FAILED;
    }

    // 单个文件上传
    @PostMapping("/upload")
    @UploadFileApi(fileName = "file")
    @ReturnType(value = "java.lang.String")
    public JsonResult upload(MultipartFile file){
        String filePath = "";
        // to do something...
        return new JsonResult(filePath);
    }

    // 多个文件上传
    @PostMapping("/uploadMulti")
    @UploadFileApi(isSingleFile = false)
    @ReturnType(value = "java.util.List<java.lang.String>")
    public JsonResult uploadMulti(StandardMultipartHttpServletRequest request){
        List<String> filePathList = new ArrayList<>();
        for(MultipartFile file : request.getFileMap().values()) {
            // to do something...
        }
        return new JsonResult(filePathList);
    }

}
```

其中：

```java
public class JsonResult implements Serializable {
    private static final int SUCCESS_CODE = 200;
    private static final String SUCCESS_MSG = "SUCCESS";
    private static final int FAILED_CODE = 500;
    private static final String FAILED_MSG = "FAILED";
    public static final JsonResult SUCCESS = new JsonResult(SUCCESS_CODE, SUCCESS_MSG);
    public static final JsonResult FAILED = new JsonResult(FAILED_CODE, FAILED_MSG);

    private Integer code;
    private String msg;
    private Object data;

    public JsonResult(){}

    public JsonResult(Integer code, String msg) {
        this.code = code;
        this.msg = msg;
    }

    public JsonResult(Integer code, String msg, Object data) {
        this.code = code;
        this.msg = msg;
        this.data = data;
    }

    public JsonResult(Object data) {
        this.code = SUCCESS_CODE;
        this.msg = SUCCESS_MSG;
        this.data = data;
    }

    // getters、setters...
}
```

### 注解详细使用说明：

#### 1、@ReturnType

   - key为空，value只能有一个值，且对应返回值对象的字段中第一个为Object类型的字段。

        > 例：@ReturnType(value = "java.util.List<net.iuyy.demo.bean.Blog>")

   - key没有加前缀
  
        > 例1：@ReturnType(key = "data", value = "java.util.List<net.iuyy.demo.bean.Blog>")
        >
        > JsonResult:data			-->		java.util.List<net.iuyy.demo.bean.Blog>
        >
        > 
        >
        > 例2：@ReturnType(key = "body, header", 
        >
        > ​									value = "net.iuyy.demo.dto.UserDto, net.iuyy.demo.bean.ResponseHeader")
        >
        > JsonResponse:body			-->		net.iuyy.demo.dto.UserDto
        >
        > JsonResponse:header		-->		net.iuyy.demo.bean.ResponseHeader
    
   - key有一个前缀（之间用冒号相连）
  
        > 例：@ReturnType(key = "JsonResult:data", value = "java.util.List<net.iuyy.demo.bean.Blog>")

   - key有多个前缀
  
        > 例1：@ReturnType(key = "JsonResult:data, UserDto:extraInfo", 
        >
        > ​									value = "net.iuyy.demo.dto.UserDto, net.iuyy.demo.bean.UserExtra")
        >
        > JsonResult:data			-->		net.iuyy.demo.dto.UserDto
        >
        > UserDto:extraInfo		-->		net.iuyy.demo.bean.UserExtra
        >
        > 
        >
        > 例2：@ReturnType(key = "JsonResult:data, JsonResult:header", 
        >
        > ​									value = "net.iuyy.demo.dto.UserDto, net.iuyy.demo.bean.ResponseHeader")
        >
        > JsonResult:data			-->		net.iuyy.demo.dto.UserDto
        >
        > JsonResult:header		-->		net.iuyy.demo.bean.ResponseHeader

#### 2、@UploadFileApi

   1）单文件上传

   > isSingleFile： 默认为true，即默认为单文件上传
   >
   > fileName：单文件上传情况下，此值不能为空。
   >
   > 例：
   >
   > ```java
   > @PostMapping("/upload")
   > @UploadFileApi(fileName = "file")
   > @ReturnType(value = "java.lang.String")
   > public JsonResult upload(MultipartFile file){
   >         String filePath = "";
   >         // to do something...
   >         return new JsonResult(filePath);
   > }
   > ```
   >

2）多文件上传
   > isSingleFile： false
   >
   > fileName：多文件上传情况下，此值可以为空。
   >
   > 例：
   >
   > ```java
   > @PostMapping("/uploadMulti")
   > @UploadFileApi(isSingleFile = false)
   > @ReturnType(value = "java.util.List<java.lang.String>")
   > public JsonResult uploadMulti(StandardMultipartHttpServletRequest request){
   >     List<String> filePathList = new ArrayList<>();
   >     for(MultipartFile file : request.getFileMap().values()) {
   >         // to do something...
   >     }
   >     return new JsonResult(filePathList);
   > }
   > ```


### 主界面说明

Put 请求接口详细：

![]( https://gitee.com/iuyy_net/iuyy-image-host/raw/master/ApiDoc/home.PNG )



Get 请求接口详细：

![]( https://gitee.com/iuyy_net/iuyy-image-host/raw/master/ApiDoc/get.PNG )

 其余的都类似，就不一一贴图了。



Get 请求接口测试：

![]( https://gitee.com/iuyy_net/iuyy-image-host/raw/master/ApiDoc/getTest.PNG )



Post 请求接口测试：

![]( https://gitee.com/iuyy_net/iuyy-image-host/raw/master/ApiDoc/postTest.PNG )



### 版本说明

#### v1.0

1、接口文档自动生成。

2、自定义返回值注解（@ReturnType）

3、接口文档访问页面（服务IP:服务端口/api/doc/）



#### v1.1

1、新增接口测试功能。

2、调整了页面布局。

3、修复部份Bugs。

#### v1.2

1、修复部份Bugs。

#### v1.3

1、新增文件上传注解（@UploadFileApi）。

2、支持文件上传接口测试。

#### v1.5

1、重构项目启动时的包扫描。

2、修复一些Bugs。

### Build Setup

``` bash
# install dependencies
npm install

# serve with hot reload at localhost:8080
npm run dev

# build for production with minification
npm run build

# build for production and view the bundle analyzer report
npm run build --report
```