YDoc使用图文攻略（基于YDoc1.0.3）

YDoc使用图文攻略

1.0.3版本可能会在swagger上嵌套显示不全的问题已经修复并重新发布预计6.5号以后恢复正常（着急可以点个Star，clone工程到本地install下即可，https://github.com/NoBugBoy/YDoc）

通用步骤

1. 创建一个springboot的web工程
   
2. 创建一个controller和一个pojo对象

//省略了get set 。。。
public class User {
   private Long id;
   private String name;
   private List<Order> us;
   private UserType type;
   public static class Order {
       private String     name;
       private BigDecimal price;
   }
}
// user Type是一个枚举类型
public enum UserType {
   ADMIN(0,"管理员"), SUPERMAN(1,"超人");
   UserType(int code,String description){
       this.code = code;
       this.description =description;

   };
   private int code;
   private String description;

}

控制器代码

@RestController
public class TestController {
   @GetMapping(value = "/get/{id}")
   public User test(@PathVariable(value = "id",name = "id") String id){
       User u = new User();
       return u;
   }
   @GetMapping(value = "/last")
   public User test(User user){
       return user;
   }
   @PostMapping(value = "/post")
   public User test1(@RequestBody User user){
       System.out.println(user);
       return user;
   }
   }
  
 

依赖maven库

      <dependency>
           <groupId>com.github.nobugboy</groupId>
           <artifactId>ydoc-spring-boot-starter</artifactId>
           <version>1.0.3</version>
       </dependency>

application.properties添加一条配置

    ydoc.enable=true

以上就是通用的基础环境，在平时的开发工程上只需额外依赖maven库和加一条配置即可

1. SwaggerUi方式

1. 如果使用 SwaggerUi方式，需在启动类或配置类上加@EnableSwagger2
2. 没了。就多了上面这一个操作

开始使用

1. 启动工程，看到如下提示证明启动成功
   
2. 访问http://localhost:8080/doc.html（如果修改了端口对应改一下）

3. 此时接口文档已经生成，只是不太友好，我们来进行一下简单的改造（yapi的改造和该方式一致，下面就不重复该步骤）

@RestController(value = "用户相关接口")
public class TestController {
    @GetMapping(value = "/get/{id}",name = "根据id获取用户")
    public User test(@PathVariable(value = "id",name = "id") String id){
        User u = new User();
        return u;
    }
    @GetMapping(value = "/last",name = "get请求测试参数描述")
    public User test(User user){
        return user;
    }
    @PostMapping(value = "/post",name = "post请求测试参数描述")
    public User test1(@RequestBody User user){
        System.out.println(user);
        return user;
    }
}

public class User {
    @ParamDesc("用户主键id")
    private Long id;
    @ParamDesc("用户名称")
    private String name;
    @ParamDesc("订单集合")
    private List<Order> us;
    @ParamDesc("用户类型")
    private UserType type;

    public static class Order {
        @ParamDesc("订单名称")
        private String     name;
        @ParamDesc("价格")
        private BigDecimal price;
    }
}
//枚举类型重写了toString方法
public enum UserType {
    ADMIN(0,"管理员"), SUPERMAN(1,"超人");
    UserType(int code,String description){
        this.code = code;
        this.description =description;

    };
    private int code;
    private String description;
    @Override
    public String toString() {
        return Arrays.stream(values())
            .map(v -> v.code +"=" + v.description)
            .collect(Collectors.joining(","));
    }

}

4. 重写启动程序，此时已经变成了非常友好的显示

发送一次请求试试

2. YApi方式

1. 安装YAPI
2. 配置项目token和YApi url即可

在YApi创建好项目，然后获取项目token，url就是访问YApi页面的路径即可

1. 在配置文件加入两行配置

ydoc.enable=true
ydoc.host=http://localhost:3000
ydoc.token=265edcb30a90a9e3eaf2209c5ac04a7cfcf290ce36ef7218101f4ddfec321964

2. 没了。就多了上面这一个操作

开始使用

1. 启动工程，访问yapi页面，接口已经有了
   
   此时所有文档已经生成完毕，点击mock地址可以发送随机mock参数。
   
   发送一次请求试试（警告可以忽略，原因是枚举默认是数值类型）
   

如果发现YApi请求不到多半是路径不对，远程的YApi也支持访问本地的localhost的server，添加多个环境即可

Swagger原生模式（本质是为了兼容已经使用了Swagger配置的工程）

对于已经使用了swagger的工程来讲引入依赖，并开启native模式

ydoc.swagger-native=true

如果想要在程序启动时同步导入到YApi直接加入下面配置即可

ydoc.host=http://localhost:3000
ydoc.token=265edcb30a90a9e3eaf2209c5ac04a7cfcf290ce36ef7218101f4ddfec321964